{"id":19501108,"url":"https://github.com/gitbookio/github-api-signature","last_synced_at":"2025-07-17T00:34:07.475Z","repository":{"id":28699206,"uuid":"119071971","full_name":"GitbookIO/github-api-signature","owner":"GitbookIO","description":"Node.js signature generator for GitHub API using a PGP key","archived":false,"fork":false,"pushed_at":"2023-10-03T08:32:59.000Z","size":277,"stargazers_count":13,"open_issues_count":13,"forks_count":11,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-07-06T01:09:33.384Z","etag":null,"topics":["github","gpg","node"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GitbookIO.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-01-26T15:59:42.000Z","updated_at":"2024-10-29T17:56:02.000Z","dependencies_parsed_at":"2024-06-19T17:37:42.446Z","dependency_job_id":"b82dccb7-c5a8-4e1a-99ad-b3bc0056c663","html_url":"https://github.com/GitbookIO/github-api-signature","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/GitbookIO/github-api-signature","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GitbookIO%2Fgithub-api-signature","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GitbookIO%2Fgithub-api-signature/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GitbookIO%2Fgithub-api-signature/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GitbookIO%2Fgithub-api-signature/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GitbookIO","download_url":"https://codeload.github.com/GitbookIO/github-api-signature/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GitbookIO%2Fgithub-api-signature/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265554805,"owners_count":23787280,"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":["github","gpg","node"],"created_at":"2024-11-10T22:11:13.436Z","updated_at":"2025-07-17T00:34:07.456Z","avatar_url":"https://github.com/GitbookIO.png","language":"TypeScript","readme":"# github-api-signature\n\n[![npm version](https://badge.fury.io/js/github-api-signature.svg)](https://badge.fury.io/js/github-api-signature)\n[![CircleCI](https://circleci.com/gh/GitbookIO/github-api-signature.svg?style=svg)](https://circleci.com/gh/GitbookIO/github-api-signature)\n\nNode.js signature generator for GitHub API using a PGP key.\n\n## Install\n\n```sh\n$ npm i github-api-signature\n```\n\nor\n\n```sh\n$ yarn add github-api-signature\n```\n\n## API\n\n### `generateKeyPair`\n\nThis method returns a `Promise` containing two properties `publicKey` and `privateKey` which are both `string`s.\n\nIt generates a public and private PGP keys pair that can be used to sign commits with GitHub API using a GitHub user's informations and a passphrase.\n\nThe public key should be added to the user's settings. The private key is then used with the `createSignature` method to sign the commit with the `committer` informations extracted from the payload sent to the API.\n\n###### Usage\n\n```js\nimport { generateKeyPair } from 'github-api-signature';\n\nconst passphrase: string = 'my secret phrase';\n\nconst user: UserInformations = {\n    name: 'Dohn Joe',\n    email: 'github@ghost.com'\n};\n\n// Optional number of bits for the generated RSA keys pair.\n// Defaults to the maximum value 4096.\nconst rsaBits = 4096;\nconst type: 'ecc' | 'rsa' = 'ecc';\n\ngenerateKeyPair(user, passphrase, rsaBits, type)\n.then((keyPair: KeyPair) =\u003e {\n    // keyPair = {\n    //     publicKey: '-----BEGIN PGP PUBLIC KEY BLOCK-----...',\n    //     privateKey: '-----BEGIN PGP PRIVATE KEY BLOCK-----...'\n    // };\n\n    // Add publicKey to Dohn Joe's GitHub account settings.\n    // Use privateKey to create commits signatures for Dohn Joe's as committer.\n});\n```\n\n###### Type definitions\n\n```js\nasync function generateKeyPair(\n    user: UserInformations,\n    passphrase: string,\n    type: 'ecc' | 'rsa' = 'ecc',\n    rsaBits: number = 4096\n): Promise\u003cKeyPair\u003e\n\ntype UserInformations = {\n    name: string,\n    email: string\n};\n\ntype KeyPair = {\n    publicKey: string,\n    privateKey: string\n};\n```\n\n### `createSignature`\n\nThis method returns a `Promise` containing a `string` which is the PGP signature that should be used on the GitHub API to sign your commit with the committer informations.\n\nUse this method with the same payload that you would send to the GitHub API `POST /repos/:owner/:repo/git/commits` endpoint.\n\nIt accepts either an already git-computed commit payload (see [GitHub's example](https://developer.github.com/v3/git/commits/#example-input)) which is the git content for a commit object, or a `CommitPayload` object.\n\nWhen using a `CommitPayload` object, the `author` argument is **mandatory**, as opposed to the optional argument for the API. This is necessary since we need to generate the commit message string with the same `date` argument as GitHub will do to verify the signature.\n\nThe `committer` argument is still optional and will default to the `author` value if omitted.\n\nIn the following example, the commit will be signed for `Dohn Joe`. Hence, `privateKey` should be generated using `Dohn Joe`'s informations.\n\n###### Usage\n\n```js\nimport { createSignature, commitToString } from 'github-api-signature';\n\nconst privateKey: string = `-----BEGIN PGP PRIVATE KEY BLOCK-----\n\n// Private key content //\n-----END PGP PRIVATE KEY BLOCK-----`;\n\nconst passphrase: string = 'my secret phrase';\n\nconst commit: CommitPayload = {\n    message: 'Commit message',\n    tree: 'tree-sha',\n    parents: ['parent-sha'],\n    author: {\n        name: 'John Doe',\n        email: 'ghost@github.com',\n        date: '2018-01-01T00:00:00.000Z'\n    },\n    // Optional committer informations\n    // Defaults to \u003cauthor\u003e\n    committer: {\n        name: 'Dohn Joe',\n        email: 'github@ghost.com',\n        date: '2018-01-01T00:00:00.000Z'\n    }\n};\n\n// Using a CommitPayload object\ncreateSignature(commit, privateKey, passphrase)\n.then((signature: string) =\u003e {\n    // signature = `-----BEGIN PGP SIGNATURE-----\n    //\n    // // Signature content\n    // -----END PGP SIGNATURE-----`;\n\n    const apiPayload = {\n        ...commit,\n        signature\n    };\n\n    // Use signature with GitHub API\n    // https://developer.github.com/v3/git/commits/#create-a-commit\n    // POST /repos/:owner/:repo/git/commits\n});\n\n// Using a git-computed commit payload string\n// commitToString returns the same format as \"git cat-file -p \u003ccommit-sha\u003e\"\nconst commitStr = commitToString(commit);\ncreateSignature(commitStr, privateKey, passphrase)\n.then((signature: string) =\u003e {\n    // ...\n});\n```\n\n###### Type definitions\n\n```js\nasync function createSignature(\n    commit: CommitPayload | string,\n    privateKey: string,\n    passphrase: string\n): Promise\u003cstring\u003e {}\n\ntype UserInformations = {\n    name: string,\n    email: string\n};\n\ntype GitHubUser = UserInformations \u0026 {\n    date: string\n};\n\ntype CommitPayload = {\n    message: string,\n    tree: string,\n    parents: string[],\n    author: GitHubUser,\n    committer?: GitHubUser\n};\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgitbookio%2Fgithub-api-signature","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgitbookio%2Fgithub-api-signature","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgitbookio%2Fgithub-api-signature/lists"}