{"id":18997696,"url":"https://github.com/s0/ghcommit","last_synced_at":"2025-04-16T20:31:36.318Z","repository":{"id":248385662,"uuid":"828567812","full_name":"s0/ghcommit","owner":"s0","description":"TypeScript library for directly changing files on GitHub","archived":false,"fork":false,"pushed_at":"2025-01-22T00:43:41.000Z","size":325,"stargazers_count":4,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-11T07:23:53.584Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/s0.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-14T14:39:56.000Z","updated_at":"2025-01-18T22:01:56.000Z","dependencies_parsed_at":"2024-07-14T15:26:00.258Z","dependency_job_id":"52bf3530-a6ab-454f-8a56-ddec64e14ed7","html_url":"https://github.com/s0/ghcommit","commit_stats":null,"previous_names":["s0/ghcommit"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s0%2Fghcommit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s0%2Fghcommit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s0%2Fghcommit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/s0%2Fghcommit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/s0","download_url":"https://codeload.github.com/s0/ghcommit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249273883,"owners_count":21241987,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T17:42:12.095Z","updated_at":"2025-04-16T20:31:36.312Z","avatar_url":"https://github.com/s0.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `@s0/ghcommit`\n\n[![View on NPM](https://badgen.net/npm/v/@s0/ghcommit)](https://www.npmjs.com/package/@s0/ghcommit)\n\nNPM / TypeScript package to commit changes GitHub repositories using the GraphQL API.\n\n## Why?\n\n- **Simplified GPG Signing:**\n\n  If you or your organisation has strict requirements\n  around requiring signed commits (i.e. via Branch Protection or Repo Rulesets), then this can make integrating CI workflows or applications that are designed to make changes to your repos quite difficult. This is because you will need to manage your own GPG keys, assign them to machine accounts (which also means it doesn't work with GitHub Apps), and securely manage and rotate them.\n\n  Instead of doing this, if you use the GitHub API to make changes to files (such as what happens when making changes to files directly in the web UI), then GitHub's internal GPG key is used, and commits are all signed and associated with the user of the access token that was used.\n\n  (And this also works with GitHub Apps too, including the GitHub Actions app).\n\n  ![](docs/verified.png)\n\n  This library has primarily been designed for use in custom Node GitHub Actions, but can be used in any Node.js or JavaScript project that needs to directly modify files in GitHub repositories.\n\n- **Simplified Git Config:**\n\n  When performing git actions via the GitHub API, all actions are always attributed to the actor whose `GITHUB_TOKEN` is being used (whether an app, or user), and this information is reflected in the git committer and author. As such, it's no longer necessary (or even possible) to specify the commit author (name and email address).\n\n  This simplifies the process of preparing your workflows for pushing changes, as you no longer need to configure the name and email address in git, and ensure they appropriately match any GPG keys used.\n\n## Usage\n\n### Installation\n\nInstall using your favourite package manager:\n\n```\npnpm install @s0/ghcommit\n```\n\n### Usage in github actions\n\nAll functions in this library that interact with the GitHub API require an octokit client that can execute GraphQL. If you are writing code that is designed to be run from within a GitHub Action, this can be done using the `@actions.github` library:\n\n```ts\nimport { getOctokit } from \"@actions/github\";\n\nconst octokit = getOctokit(process.env.GITHUB_TOKEN);\n```\n\n### Importing specific modules\n\nTo allow for you to produce smaller bundle sizes, the functionality exposed in this package is grouped into specific modules that only import the packages required for their use. We recommend that you import from the specific modules rather than the root of the package.\n\n## API\n\nAll the functions below accept a single object as its argument, and share the following base arguments:\n\n\u003c!-- TODO: point to some generated docs instead of including a code snippet --\u003e\n\n```ts\n{\n  octokit: GitHubClient;\n  owner: string;\n  repo: string;\n  branch: string;\n  /**\n   * Push the commit even if the branch exists and does not match what was\n   * specified as the base.\n   */\n  force?: boolean;\n  /**\n   * The commit message\n   */\n  message: string | CommitMessage;\n  log?: Logger;\n}\n```\n\n### `commitChangesFromRepo`\n\nThis function will take an existing repository on your filesystem (defaulting to the current working directory). This function is good to use if you're usually working within the context of a git repository, such as after running `@actions/checkout` in github actions.\n\nIn addition to `CommitFilesBasedArgs`, this function has the following arguments:\n\n```ts\n{\n  /**\n   * The base commit to build your changes on-top of\n   *\n   * @default HEAD\n   */\n  base?: {\n    commit: string;\n  };\n  /**\n   * The root of the repository.\n   *\n   * @default process.cwd()\n   */\n  repoDirectory?: string;\n}\n```\n\nExample:\n\n```ts\nimport { context, getOctokit } from \"@actions/github\";\nimport { commitChangesFromRepo } from \"@s0/ghcommit/git\";\n\nconst octokit = getOctokit(process.env.GITHUB_TOKEN);\n\n// Commit \u0026 push the files from the current directory\n// e.g. if you're just using @ations/checkout\nawait commitChangesFromRepo({\n  octokit,\n  ...context.repo,\n  branch: \"new-branch-to-create\",\n  message: \"[chore] do something\",\n});\n\n// Commit \u0026 push the files from a specific directory\n// where we've cloned a repo, and made changes to files\nawait commitChangesFromRepo({\n  octokit,\n  owner: \"my-org\",\n  repository: \"my-repo\",\n  branch: \"another-new-branch-to-create\",\n  message: \"[chore] do something else\\n\\nsome more details\",\n  repoDirectory: \"/tmp/some-repo\",\n});\n\n// Commit \u0026 push the files from the current directory,\n// but ensure changes from any locally-made commits are also included\nawait commitChangesFromRepo({\n  octokit,\n  ...context.repo,\n  branch: \"another-new-branch-to-create\",\n  message: {\n    headline: \"[chore] do something else\",\n    body: \"some more details\",\n  },\n  base: {\n    // This will be the original sha from the workflow run,\n    // even if we've made commits locally\n    commit: context.sha,\n  },\n});\n```\n\n### `commitFilesFromDirectory`\n\nThis function will add or delete specific files from a repository's branch based on files found on the local filesystem. This is good to use when there are specific files that need to be updated on a branch, or if many changes may have been made locally, but only some files need to be pushed.\n\nIn addition to `CommitFilesBasedArgs`, this function has the following arguments:\n\n```ts\n{\n  /**\n   * The current branch, tag or commit that the new branch should be based on.\n   */\n  base: GitBase;\n  /**\n   * The directory to consider the root of the repository when calculating\n   * file paths\n   */\n  workingDirectory?: string;\n  /**\n   * The file paths, relative to {@link workingDirectory},\n   * to add or delete from the branch on GitHub.\n   */\n  fileChanges: {\n    /** File paths, relative to {@link workingDirectory}, to remove from the repo. */\n    additions?: string[];\n    /** File paths, relative to the repository root, to remove from the repo. */\n    deletions?: string[];\n  };\n}\n```\n\nExample:\n\n```ts\nimport { context, getOctokit } from \"@actions/github\";\nimport { commitFilesFromDirectory } from \"@s0/ghcommit/fs\";\n\nconst octokit = getOctokit(process.env.GITHUB_TOKEN);\n\n// Commit the changes to package.json and package-lock.json\n// based on the main branch\nawait commitFilesFromDirectory({\n  octokit,\n  ...context.repo,\n  branch: \"new-branch-to-create\",\n  message: \"[chore] do something\",\n  base: {\n    branch: \"main\",\n  },\n  workingDirectory: \"foo/bar\",\n  fileChanges: {\n    additions: [\"package-lock.json\", \"package.json\"],\n  },\n});\n\n// Push just the index.html file to a new branch called docs, based off the tag v1.0.0\nawait commitFilesFromDirectory({\n  octokit,\n  ...context.repo,\n  branch: \"docs\",\n  message: \"[chore] do something\",\n  force: true, // Overwrite any existing branch\n  base: {\n    tag: \"v1.0.0\",\n  },\n  workingDirectory: \"some-dir\",\n  fileChanges: {\n    additions: [\"index.html\"],\n  },\n});\n```\n\n### `commitFilesFromBuffers`\n\nThis function will add or delete specific files from a repository's branch based on Node.js `Buffers` that can be any binary data in memory. This is useful for when you want to make changes to a repository / branch without cloning a repo or interacting with a filesystem.\n\nIn addition to `CommitFilesBasedArgs`, this function has the following arguments:\n\n```ts\n{\n  /**\n   * The current branch, tag or commit that the new branch should be based on.\n   */\n  base: GitBase;\n  /**\n   * The file changes, relative to the repository root, to make to the specified branch.\n   */\n  fileChanges: {\n    additions?: Array\u003c{\n      path: string;\n      contents: Buffer;\n    }\u003e;\n    deletions?: string[];\n  };\n}\n```\n\nExample:\n\n```ts\nimport { context, getOctokit } from \"@actions/github\";\nimport { commitFilesFromBuffers } from \"@s0/ghcommit/node\";\n\nconst octokit = getOctokit(process.env.GITHUB_TOKEN);\n\n// Add a file called hello-world\nawait commitFilesFromBuffers({\n  octokit,\n  ...context.repo,\n  branch: \"new-branch-to-create\",\n  message: \"[chore] do something\",\n  base: {\n    branch: \"main\",\n  },\n  fileChanges: {\n    additions: [\n      {\n        path: \"hello/world.txt\",\n        contents: Buffer.alloc(1024, \"Hello, world!\"),\n      },\n    ],\n  },\n});\n```\n\n## Other Tools / Alternatives\n\n- [planetscale/ghcommit](https://github.com/planetscale/ghcommit) - Go library for committing to GitHub using graphql\n- [planetscale/ghcommit-action](https://github.com/planetscale/ghcommit-action) - GitHub Action to detect file changes and commit using the above library\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fs0%2Fghcommit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fs0%2Fghcommit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fs0%2Fghcommit/lists"}