Skip to content

Latest commit

 

History

History
238 lines (186 loc) · 10.5 KB

README.md

File metadata and controls

238 lines (186 loc) · 10.5 KB
Raw

GitHub App Token Authoriser

Build Status (latest push) Stable Version Latest Release

This JavaScript GitHub Action 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.

Use Cases

This is useful for when secrets.GITHUB_TOKEN's limitations are too restrictive and a personal access token is not suitable.

The repo scoped secrets.GITHUB_TOKEN has limitations such as:

  • Cannot be used to checkout other private or internal repositories.
  • Have their permissions scoped at the workflow level - not by admins.
  • Cannot trigger a workflow run from another workflow.

A common workaround for individual use is to use a Personal Access Token but this has significant security, maintenance and auditability issues.

Github recommends using GitHub Apps as a workaround to automate authentication to Github Services that isn't provided out of the box by Github / Actions.

Example Workflows

Get a token with all the permissions of the GitHub Application

jobs:
  get-temp-token:
    runs-on: ubuntu-latest
    steps:
      - name: Get Token
        id: get_workflow_token
        uses: sammcj/github-app-installation-token@main # or a specific version
        with:
          application_id: ${{ secrets.AUTHENTICATOR_APPLICATION_ID }}
          application_private_key: ${{ secrets.AUTHENTICATOR_APPLICATION_PRIVATE_KEY }}

      - name: Use Application Token to checkout a repository
        uses: actions/checkout@v3
        env:
          GITHUB_TOKEN: ${{ steps.get_workflow_token.outputs.token }}
          ....

Get a token with a limited subset of the permissions of the Github Application, in this case adding the actions:write and issues:read permissions.

jobs:
  get-temp-token:
    runs-on: ubuntu-latest
    steps:
      - name: Get Token
        id: get_workflow_token
        sammcj/github-app-installation-token@main # or a specific version
        with:
          application_id: ${{ secrets.AUTHENTICATOR_APPLICATION_ID }}
          application_private_key: ${{ secrets.AUTHENTICATOR_APPLICATION_PRIVATE_KEY }}
          permissions: "actions:write,issues:read"

      - name: Use Application Token to checkout a repository
        uses: actions/checkout@v4
        env:
          GITHUB_TOKEN: ${{ steps.get_workflow_token.outputs.token }}
        with:
          ....

Get a token with all the permissions of the Github Application that is installed on an organisation

jobs:
  get-temp-token:
    runs-on: ubuntu-latest
    steps:
      - name: Get Token
        id: get_workflow_token
        uses: sammcj/github-app-installation-token@main # or a specific version
        with:
          application_id: ${{ secrets.AUTHENTICATOR_APPLICATION_ID }}
          application_private_key: ${{ secrets.AUTHENTICATOR_APPLICATION_PRIVATE_KEY }}
          organisation: CattleDip

      - name: Use Application Token to checkout a repository
        uses: actions/checkout@v4
        env:
          GITHUB_TOKEN: ${{ steps.get_workflow_token.outputs.token }}
        with:
          ....

Inputs

inputs:
  application_private_key:
    description: GitHub Application Private Key value.
    required: true
  application_id:
    description: GitHub Application ID value.
    required: true
  application_installation_id:
    description: GitHub Install Application ID value.
    required: false
  permissions:
    description: "The permissions to request e.g. issues:read,secrets:write,packages:read. Defaults to all available permissions"
    required: false
  org:
    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.
    required: false
  owner:
    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.
    required: false
  repo:
    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.
    required: false
  github_api_base_url:
    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.
    required: false
  token_lifetime:
    description: The lifetime of the token in seconds, defaults to 600 seconds (10 minutes).
    required: false

Outputs

outputs:
  token:
    description: A valid token representing the Application that can be used to access what the Application has been scoped to access.
  expires_at:
    description: The date and time when the token will expire (UTC).
  permissions_requested:
    description: The permissions that were requested for the token.
  permissions_granted:
    description: The permissions that were granted for the token.

Requirements

  • A new or existing GitHub Application with the access scopes required
  • A private key for the GitHub Application
  • The GitHub Application installed on the repository that the GitHub Actions Workflow will execute from

Creating a GitHub Application

You will need to have a GitHub Application that is scoped with the necessary permissions for the token that you want to retrieve at runtime.

To create a GitHub Application you can follow the steps available at https://docs.github.com/en/developers/apps/creating-a-github-app

The important configuration details for the application are:

  • GitHub App name a human readable application name that is unique within GitHub.com
  • Description some details about your application and what you intend to use it for
  • Homepage URL needs to be set to something as long as it is a URL
  • Expire user authorization tokens should be checked so as to expire any tokens that are issued
  • Webhook Active checkbox should be unchecked
  • Repository permissions, Organisation permissions and/or User permissions allows the access required for the token that will be issued
  • Where can this GitHub App be installed? should be scoped to your desired audience (the current account, or any account)

Once the application has been created you will be taken to the General settings page for the new application. The GitHub Application will be issued an App ID which you can see in the About section, take note of this for later use in the Actions workflow.

On the General settings page for the application, at the bottom there is a Private keys section that you can use to generate a private key that can be utilized to authenticate as the application. Generate a new private key and store the information for later use.

Note: the private keys can and should be rotated periodically to limit the risks of them being exposed in use.

Install the GitHub Application

Once you have the GitHub Application defined, you will need to install the application on the target organisation or repository/ repositories that you want it to have access to. These will be any repositories that you want to gather information from or want the application to modify as per the scopes that were defined when the application was installed.

Note: The GitHub Application will need to be installed on the organisation and or repository that you are executing the GitHub Actions workflow from, as the implementation requires this to be able to generate the access tokens.

Contributions

As always - pull requests are welcomed.

Development

First set the following environment variables:

  • GITHUB_APPLICATION_PRIVATE_KEY - The private key for the GitHub Application
  • GITHUB_APPLICATION_ID - The ID of the GitHub Application

and either:

  • GITHUB_ORG - The GitHub Organisation to get the application installation for, if not specified will use the current repository instead or
  • GITHUB_REPOSITORY_OWNER - The GitHub Repository Owner to get the application installation for, if not specified will use the current repository instead

e.g:

export GITHUB_APPLICATION_PRIVATE_KEY='-----BEGIN RSA PRIVATE KEY-----\\n<your private key>\\n-----END RSA PRIVATE KEY-----'
export GITHUB_APPLICATION_ID=<applicationId>
export GITHUB_APPLICATION_ORG=<organisation>

Then run the following commands:

npm ci
npm run lint
npm run test
npm run build # Required as uses ncc to compile the action

Security

This action is built using the official Github Octokit API library to authenticate with Github and generate a token.

If you have any concerns about the security of this action, please raise an issue.