GitHub API token authentication for GitHub Actions

@octokit/auth-action is one of GitHub’s authentication strategies.

It does not require any configuration, but instead reads the GITHUB_TOKEN environment variable that is provided to GitHub Actions.

• Usage
• createActionAuth()
• auth()
• Authentication object
• auth.hook(request, route, options) or auth.hook(request, options)
• Find more information
• License

Install with npm install @octokit/auth-action

import { createActionAuth } from "@octokit/auth-action";

const auth = createActionAuth();
const authentication = await auth();
// {
//   type: 'token',
//   token: 'v1.1234567890abcdef1234567890abcdef12345678',
//   tokenType: 'oauth'
// }

The createActionAuth() method has no options.

It expects the GITHUB_TOKEN variable to be set which is provided to GitHub Actions, but has to be configured explicitly.

GITHUB_TOKEN can be passed as environment variable using env:

steps:
  - name: My action
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

or using with:

steps:
  - name: My action
    with:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

or named token using with:

steps:
  - name: My action
    with:
      token: ${{ secrets.GITHUB_TOKEN }}

GITHUB_TOKEN can be set to any of the repository's secret, e.g. if you want to use a personal access token.

steps:
  - name: My first action
    env:
      GITHUB_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}

createActionAuth() is also checking for the GITHUB_ACTION variable to be present to make sure that it runs within a GitHub Action.

If GITHUB_ACTION or neither GITHUB_TOKEN, INPUT_GITHUB_TOKEN or INPUT_TOKEN are set an error is thrown.

The auth() method has no options. It returns a promise which resolves with the authentication object.

auth.hook() hooks directly into the request life cycle. It authenticates the request using the provided token.

The request option is an instance of @octokit/request. The route/options parameters are the same as for the request() method.

auth.hook() can be called directly to send an authenticated request

const { data: authorizations } = await auth.hook(
  request,
  "GET /authorizations",
);

Or it can be passed as option to request().

const requestWithAuth = request.defaults({
  request: {
    hook: auth.hook,
  },
});

const { data: authorizations } = await requestWithAuth("GET /authorizations");

auth() does not send any requests, it only retrieves the token from the environment variable and transforms the provided token string into an authentication object.

The GITHUB_TOKEN provided to GitHub Actions is an installation token with all permissions provided. You can use it for git commands, too. Learn more about the differences in token authentication at @octokit/auth-action.

MIT