{"id":20188963,"url":"https://github.com/sammcj/github-app-installation-token","last_synced_at":"2025-04-10T07:43:21.061Z","repository":{"id":58835899,"uuid":"534038074","full_name":"sammcj/github-app-installation-token","owner":"sammcj","description":"Generates Github tokens using a Github App install","archived":false,"fork":false,"pushed_at":"2024-12-07T10:12:45.000Z","size":90737,"stargazers_count":5,"open_issues_count":8,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-23T14:17:02.698Z","etag":null,"topics":["actions","authentication","security","token","workflow"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/sammcj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"2022-09-08T03:40:14.000Z","updated_at":"2024-11-18T06:33:39.000Z","dependencies_parsed_at":"2024-02-10T16:28:05.406Z","dependency_job_id":"95a0da98-a323-487b-8a52-ce585db5f03d","html_url":"https://github.com/sammcj/github-app-installation-token","commit_stats":{"total_commits":89,"total_committers":3,"mean_commits":"29.666666666666668","dds":0.6067415730337078,"last_synced_commit":"c37252113f07556fe6613f47a68e96b1983bfc87"},"previous_names":[],"tags_count":131,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sammcj%2Fgithub-app-installation-token","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sammcj%2Fgithub-app-installation-token/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sammcj%2Fgithub-app-installation-token/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sammcj%2Fgithub-app-installation-token/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sammcj","download_url":"https://codeload.github.com/sammcj/github-app-installation-token/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248179711,"owners_count":21060685,"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":["actions","authentication","security","token","workflow"],"created_at":"2024-11-14T03:33:00.437Z","updated_at":"2025-04-10T07:43:21.035Z","avatar_url":"https://github.com/sammcj.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GitHub App Token Authoriser\n\n[![Build Status (latest push)](https://github.com/sammcj/github-app-installation-token/workflows/Bump%20version/badge.svg)](https://github.com/sammcj/github-app-installation-token/workflows/bump-version)\n[![Stable Version](https://img.shields.io/github/v/tag/sammcj/github-app-installation-token)](https://img.shields.io/github/v/tag/sammcj/github-app-installation-token)\n[![Latest Release](https://img.shields.io/github/v/release/sammcj/github-app-installation-token?color=%233D9970)](https://img.shields.io/github/v/release/sammcj/github-app-installation-token?color=%233D9970)\n\nThis [JavaScript GitHub Action](https://help.github.com/en/actions/building-actions/about-actions#javascript-actions) can be used to act as a GitHub App that with a private key and installation ID to generate a short lived (and optionally de-scoped) token that can be used to authenticate with the GitHub API.\n\n![](https://github.com/sammcj/github-app-installation-token/assets/862951/7f8011e2-ed98-4453-a007-eeabecfc84ed)\n\n- [GitHub App Token Authoriser](#github-app-token-authoriser)\n  - [Use Cases](#use-cases)\n  - [Example Workflows](#example-workflows)\n    - [Inputs](#inputs)\n    - [Outputs](#outputs)\n  - [Requirements](#requirements)\n    - [Creating a GitHub Application](#creating-a-github-application)\n      - [Install the GitHub Application](#install-the-github-application)\n  - [Contributions](#contributions)\n    - [Development](#development)\n  - [Security](#security)\n\n## Use Cases\n\nThis is useful for when `secrets.GITHUB_TOKEN`'s limitations are too restrictive and a personal access token is not suitable.\n\nThe repo scoped [`secrets.GITHUB_TOKEN`](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token)\nhas limitations such as:\n\n- Cannot be used to checkout other private or internal repositories.\n- Have their permissions scoped at the workflow level - not by admins.\n- Cannot trigger a workflow run from another workflow.\n\nA common workaround for individual use is to use a [Personal Access Token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line) but this has significant security, maintenance and auditability issues.\n\nGithub recommends using [GitHub Apps](https://developer.github.com/apps/differences-between-apps/#machine-vs-bot-accounts) as a\nworkaround to automate authentication to Github Services that isn't provided out of the box by Github / Actions.\n\n## Example Workflows\n\nGet a token with all the permissions of the GitHub Application\n\n```yaml\njobs:\n  get-temp-token:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Get Token\n        id: get_workflow_token\n        uses: sammcj/github-app-installation-token@main # or a specific version\n        with:\n          application_id: ${{ secrets.AUTHENTICATOR_APPLICATION_ID }}\n          application_private_key: ${{ secrets.AUTHENTICATOR_APPLICATION_PRIVATE_KEY }}\n\n      - name: Use Application Token to checkout a repository\n        uses: actions/checkout@v3\n        env:\n          GITHUB_TOKEN: ${{ steps.get_workflow_token.outputs.token }}\n          ....\n```\n\nGet a token with a limited subset of the permissions of the Github Application, in this case adding the\n`actions:write` and `issues:read` permissions.\n\n```yaml\njobs:\n  get-temp-token:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Get Token\n        id: get_workflow_token\n        sammcj/github-app-installation-token@main # or a specific version\n        with:\n          application_id: ${{ secrets.AUTHENTICATOR_APPLICATION_ID }}\n          application_private_key: ${{ secrets.AUTHENTICATOR_APPLICATION_PRIVATE_KEY }}\n          permissions: \"actions:write,issues:read\"\n\n      - name: Use Application Token to checkout a repository\n        uses: actions/checkout@v4\n        env:\n          GITHUB_TOKEN: ${{ steps.get_workflow_token.outputs.token }}\n        with:\n          ....\n```\n\nGet a token with all the permissions of the Github Application that is installed on an organisation\n\n```yaml\njobs:\n  get-temp-token:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Get Token\n        id: get_workflow_token\n        uses: sammcj/github-app-installation-token@main # or a specific version\n        with:\n          application_id: ${{ secrets.AUTHENTICATOR_APPLICATION_ID }}\n          application_private_key: ${{ secrets.AUTHENTICATOR_APPLICATION_PRIVATE_KEY }}\n          organisation: CattleDip\n\n      - name: Use Application Token to checkout a repository\n        uses: actions/checkout@v4\n        env:\n          GITHUB_TOKEN: ${{ steps.get_workflow_token.outputs.token }}\n        with:\n          ....\n```\n\n### Inputs\n\n```yaml\ninputs:\n  application_private_key:\n    description: GitHub Application Private Key value.\n    required: true\n  application_id:\n    description: GitHub Application ID value.\n    required: true\n  application_installation_id:\n    description: GitHub Install Application ID value.\n    required: false\n  permissions:\n    description: \"The permissions to request e.g. issues:read,secrets:write,packages:read. Defaults to all available permissions\"\n    required: false\n  org:\n    description: The GitHub Organisation to get the application installation for, if not specified will use the current repository instead. This is not normally needed as the workflow will be running in the context of a repository / org.\n    required: false\n  owner:\n    description: The GitHub Owner to get the application installation for, if not specified will use the current repository instead. This is not normally needed as the workflow will be running in the context of a repository / org.\n    required: false\n  repo:\n    description: The GitHub Repository to get the application installation for, if not specified will use the current repository instead (owner must also be specified). This is not normally needed as the workflow will be running in the context of a repository / org.\n    required: false\n  github_api_base_url:\n    description: The GitHub API base URL to use, no needed it working within the same GitHub instance as the workflow as it will get picked up from the environment. This not usually needed and is mainly for testing purposes.\n    required: false\n  token_lifetime:\n    description: The lifetime of the token in seconds, defaults to 600 seconds (10 minutes).\n    required: false\n```\n\n### Outputs\n\n```yaml\noutputs:\n  token:\n    description: A valid token representing the Application that can be used to access what the Application has been scoped to access.\n  expires_at:\n    description: The date and time when the token will expire (UTC).\n  permissions_requested:\n    description: The permissions that were requested for the token.\n  permissions_granted:\n    description: The permissions that were granted for the token.\n```\n\n## Requirements\n\n- A new or existing GitHub Application with the access scopes required\n- A private key for the GitHub Application\n- The GitHub Application installed on the repository that the GitHub Actions Workflow will execute from\n\n### Creating a GitHub Application\n\nYou will need to have a GitHub Application that is scoped with the necessary permissions for the token that you want to\nretrieve at runtime.\n\nTo create a GitHub Application you can follow the steps available at \u003chttps://docs.github.com/en/developers/apps/creating-a-github-app\u003e\n\nThe important configuration details for the application are:\n\n- `GitHub App name` a human readable application name that is unique within GitHub.com\n- `Description` some details about your application and what you intend to use it for\n- `Homepage URL` needs to be set to something as long as it is a URL\n- `Expire user authorization tokens` should be checked so as to expire any tokens that are issued\n- `Webhook` `Active` checkbox should be unchecked\n- `Repository permissions`, `Organisation permissions` and/or `User permissions` allows the access required for the token that will be issued\n- `Where can this GitHub App be installed?` should be scoped to your desired audience (the current account, or any account)\n\nOnce the application has been created you will be taken to the `General` settings page for the new application.\nThe GitHub Application will be issued an `App ID` which you can see in the `About` section, take note of this for later\nuse in the Actions workflow.\n\nOn the `General` settings page for the application, at the bottom there is a `Private keys` section that you can use to\ngenerate a private key that can be utilized to authenticate as the application.\nGenerate a new private key and store the information for later use.\n\n_Note: the private keys can and should be rotated periodically to limit the risks of them being exposed in use._\n\n#### Install the GitHub Application\n\nOnce you have the GitHub Application defined, you will need to install the application on the target organisation or repository/\nrepositories that you want it to have access to. These will be any repositories that you want to gather information\nfrom or want the application to modify as per the scopes that were defined when the application was installed.\n\n_Note: The GitHub Application will need to be installed on the organisation and or repository that you are executing\nthe GitHub Actions workflow from, as the implementation requires this to be able to generate the access tokens_.\n\n## Contributions\n\nAs always - pull requests are welcomed.\n\n### Development\n\nFirst set the following environment variables:\n\n- `GITHUB_APPLICATION_PRIVATE_KEY` - The private key for the GitHub Application\n- `GITHUB_APPLICATION_ID` - The ID of the GitHub Application\n\nand either:\n\n- `GITHUB_ORG` - The GitHub Organisation to get the application installation for, if not specified will use the current repository instead\nor\n- `GITHUB_REPOSITORY_OWNER` - The GitHub Repository Owner to get the application installation for, if not specified will use the current repository instead\n\ne.g:\n\n```shell\nexport GITHUB_APPLICATION_PRIVATE_KEY='-----BEGIN RSA PRIVATE KEY-----\\\\n\u003cyour private key\u003e\\\\n-----END RSA PRIVATE KEY-----'\nexport GITHUB_APPLICATION_ID=\u003capplicationId\u003e\nexport GITHUB_APPLICATION_ORG=\u003corganisation\u003e\n```\n\nThen run the following commands:\n\n```shell\nnpm ci\nnpm run lint\nnpm run test\nnpm run build # Required as uses ncc to compile the action\n```\n\n## Security\n\nThis action is built using the official Github [Octokit](https://github.com/octokit) API library to authenticate with Github and generate a token.\n\nIf you have any concerns about the security of this action, please raise an issue.\n\n- [Github Apps - Authenticating as an installation](https://docs.github.com/en/developers/apps/authenticating-with-github-apps#authenticating-as-an-installation)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsammcj%2Fgithub-app-installation-token","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsammcj%2Fgithub-app-installation-token","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsammcj%2Fgithub-app-installation-token/lists"}