@octokit/auth-action
v5.1.1
Published
GitHub API token authentication for GitHub Actions
Downloads
187,285
Readme
auth-action.js
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)
orauth.hook(request, options)
- Find more information
- License
Usage
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'
// }
[!IMPORTANT] As we use conditional exports, you will need to adapt your
tsconfig.json
by setting"moduleResolution": "node16", "module": "node16"
.See the TypeScript docs on package.json "exports". See this helpful guide on transitioning to ESM from @sindresorhus
createActionAuth()
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.
auth()
The auth()
method has no options. It returns a promise which resolves with the authentication object.
Authentication object
auth.hook(request, route, options)
or auth.hook(request, options)
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");
Find more information
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.