feat: initial version (#1)

Co-authored-by: Parker Brown <17183625+parkerbxyz@users.noreply.github.com>
Co-authored-by: Gregor Martynus <gr2m@users.noreply.github.com>

.github/workflows/release.yml

@@ -0,0 +1,37 @@
+name: release
+"on":
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+jobs:
+  release:
+    name: release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          cache: npm
+          node-version: lts/*
+      - run: npm ci
+      - run: npm run build
+      - uses: ./ # Uses the action in the root directory
+        id: app-token
+        with:
+          app_id: ${{ vars.RELEASER_APP_ID }}
+          private_key: ${{ secrets.RELEASER_APP_PRIVATE_KEY }}
+
+      - id: commit
+        uses: stefanzweifel/git-auto-commit-action@v4
+        with:
+          commit_message: "build: update dist files"
+      - run: npm i semantic-release-plugin-github-breaking-version-tag
+      - run: npx semantic-release
+        env:
+          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}

.github/workflows/test.yml

@@ -0,0 +1,25 @@
+on: [push]
+
+jobs:
+  demo:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: '16.16'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run build
+      - uses: ./ # Uses the action in the root directory
+        id: demo
+        with:
+          app_id: ${{ secrets.APP_ID }}
+          private_key: ${{ secrets.PRIVATE_KEY }}
+      - uses: octokit/request-action@v2.x
+        id: get-repository
+        env:
+          GITHUB_TOKEN: ${{ steps.demo.outputs.token }}
+        with:
+          route: GET /installation/repositories
+      - run: echo '${{ steps.get-repository.outputs.data }}'

.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+.env

LICENSE

@@ -1,6 +1,7 @@
 The MIT License (MIT)
 
-Copyright (c) 2023 GitHub, Inc. and contributors
+Copyright (c) 2023 Gregor Martynus
+Copyright (c) 2023 Parker Brown
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,9 +1,109 @@
-# 🚧 Work in progress - see [#1](https://github.com/gr2m/app-token-action/pull/1)
-
 # `app-token-action`
 
 > GitHub Action for creating a GitHub App Installation Access Token
 
+## Usage
+
+In order to use this action, you need to:
+
+1. [Register new GitHub App](https://docs.github.com/apps/creating-github-apps/setting-up-a-github-app/creating-a-github-app)
+2. [Store the App's ID in your repository environment variables](https://docs.github.com/actions/learn-github-actions/variables#defining-configuration-variables-for-multiple-workflows) (example: `APP_ID`)
+3. [Store the App's private key in your repository secrets](https://docs.github.com/actions/security-guides/encrypted-secrets?tool=webui#creating-encrypted-secrets-for-a-repository) (example: `PRIVATE_KEY`)
+
+### Minimal usage
+
+```yaml
+on: [issues]
+
+jobs:
+  hello-world:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: gr2m/app-token-action@v1
+        id: app-token
+        with:
+          app_id: ${{ vars.APP_ID }}
+          private_key: ${{ secrets.PRIVATE_KEY }}
+      - uses: peter-evans/create-or-update-comment@v3
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          issue-number: ${{ github.event.issue.number }}
+          body: "Hello, World!"
+```
+
+### Limit the app's permissions and access to repositories
+
+```yaml
+on: [issues]
+
+jobs:
+  with-scoped-token:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: gr2m/app-token-action@v1
+        id: app-token
+        with:
+          # required
+          app_id: ${{ vars.APP_ID }}
+          private_key: ${{ secrets.PRIVATE_KEY }}
+      # do something with the token
+```
+
+### Use app token with `actions/checkout`
+
+```yaml
+on: [pull_request]
+
+jobs:
+  auto-format:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: gr2m/app-token-action@v1
+        id: app-token
+        with:
+          # required
+          app_id: ${{ vars.APP_ID }}
+          private_key: ${{ secrets.PRIVATE_KEY }}
+      - uses: actions/checkout@v3
+        with:
+          token: ${{ steps.app-token.outputs.token }}
+          ref: ${{ github.head_ref }}
+          # Make sure the value of GITHUB_TOKEN will not be persisted in repo's config
+          persist-credentials: false
+      - uses: creyD/prettier_action@v4.3
+        with:
+          github_token: ${{ steps.app-token.outputs.token }}
+```
+
+## Inputs
+
+### `app_id`
+
+**Required:** GitHub app ID.
+
+### `private_key`
+
+**Required:** GitHub app private key.
+
+## Outputs
+
+### `token`
+
+GitHub installation access token.
+
+## How it works
+
+The action creates an installation access token using [the `POST /app/installations/{installation_id}/access_tokens` endpoint](https://docs.github.com/rest/apps/apps?apiVersion=2022-11-28#create-an-installation-access-token-for-an-app). By default,
+
+1. The token is scoped to the current repository
+2. The token inherits all the installation's permissions
+3. The token is set as output `token` which can be used in subsequent steps
+4. The token is revoked in the `post` step of the action, which means it cannot be passed to another job.
+5. The token is masked, it cannot be logged accidentally. That is not a feature by the action, but by the GitHub Actions runner itself, due to the specific format of GitHub tokens.
+
+> **Note**
+> Installation permissions can differ from the app's permissions they belong to. Installation permissions are set when an app is installed on an account. When the app adds more permissions after the installation, an account administrator will have to approve the new permissions before they are set on the installation.
+
 ## License
 
 [MIT](LICENSE)

action.yml

@@ -0,0 +1,17 @@
+name: 'github-app-token'
+description: ''
+author: 'Gregor Martynus and Parker Brown'
+inputs:
+  app_id:
+    description: 'GitHub app ID'
+    required: true
+  private_key:
+    description: 'GitHub app private key'
+    required: true
+outputs:
+  token:
+    description: 'GitHub installation access token'
+runs:
+  using: 'node16'
+  main: 'dist/main.cjs'
+  post: 'dist/post.cjs'