toolkit/packages/github/README.md

@actions/github

A hydrated Octokit client.

Usage

Returns an Octokit client. See https://octokit.github.io/rest.js for the API.

const github = require('@actions/github');
const core = require('@actions/core');

async function run() {
    // This should be a token with access to your repository scoped in as a secret.
    // The YML workflow will need to set myToken with the GitHub Secret Token
    // myToken: ${{ secrets.GITHUB_TOKEN }}
    // https://help.github.com/en/actions/automating-your-workflow-with-github-actions/authenticating-with-the-github_token#about-the-github_token-secret
    const myToken = core.getInput('myToken');

    const octokit = new github.GitHub(myToken);

    const { data: pullRequest } = await octokit.pulls.get({
        owner: 'octokit',
        repo: 'rest.js',
        pull_number: 123,
        mediaType: {
          format: 'diff'
        }
    });

    console.log(pullRequest);
}

run();

You can pass client options (except auth, which is handled by the token argument), as specified by Octokit, as a second argument to the GitHub constructor.

You can also make GraphQL requests. See https://github.com/octokit/graphql.js for the API.

const result = await octokit.graphql(query, variables);

Finally, you can get the context of the current action:

const github = require('@actions/github');

const context = github.context;

const newIssue = await octokit.issues.create({
  ...context.repo,
  title: 'New issue!',
  body: 'Hello Universe!'
});

Context Payload Casting

The GitHub Webhook Event payload is provided as a part of the context. Based on the type of event that triggered your workflow, the structure of that object may change. You can cast this field to access these members in a type safe way.

const github = require('@actions/github');

const payload = github.context.payload
if ((payload as Webhooks.WebhookPayloadPush).head_commit) {
  core.info(
    `The head commit is: ${
      (payload as Webhooks.WebhookPayloadPush).head_commit
    }`
  )
}

There may be cases where multiple events have a field you need. For example, we can get the issue number field from the issue event and the issue_comment event

const github = require('@actions/github');
const payload = github.context.payload
if (payload && "issue" in payload) {
  core.info(`The issue number is: ${JSON.stringify(payload.issue.number)}`)
}