or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

index.md

tile.json

@actions/github

@actions/github is a hydrated Octokit client specifically designed for GitHub Actions. It provides an authenticated GitHub API client that automatically handles authentication, proxy settings, and GitHub Enterprise Server (GHES) base URLs, plus comprehensive GitHub Actions context information.

Package Information

Package Name: @actions/github
Package Type: npm
Language: TypeScript
Installation: npm install @actions/github

Core Imports

import { getOctokit, context } from "@actions/github";

For CommonJS:

const { getOctokit, context } = require("@actions/github");

Advanced usage with utilities:

import { GitHub, getOctokitOptions, defaults } from "@actions/github/lib/utils";

Basic Usage

import { getOctokit, context } from "@actions/github";
import * as core from "@actions/core";

async function run() {
  // Get GitHub token from action input or secret
  const myToken = core.getInput('myToken');
  
  // Create authenticated Octokit client
  const octokit = getOctokit(myToken);
  
  // Use REST API
  const { data: pullRequest } = await octokit.rest.pulls.get({
    owner: 'octokit',
    repo: 'rest.js',
    pull_number: 123,
  });
  
  // Use GraphQL API
  const result = await octokit.graphql(`
    query($owner: String!, $repo: String!) {
      repository(owner: $owner, name: $repo) {
        issues(first: 10) {
          nodes {
            title
            number
          }
        }
      }
    }
  `, {
    owner: context.repo.owner,
    repo: context.repo.repo
  });
  
  // Create issue using context
  const newIssue = await octokit.rest.issues.create({
    ...context.repo,
    title: 'New issue!',
    body: 'Hello Universe!'
  });
}

Capabilities

Octokit Client Creation

Creates an authenticated Octokit client with GitHub Actions-specific configuration.

/**
 * Returns a hydrated Octokit ready to use for GitHub Actions
 * @param token - The repo PAT or GITHUB_TOKEN
 * @param options - Optional Octokit configuration options
 * @param additionalPlugins - Additional Octokit plugins to include
 * @returns Configured Octokit client instance
 */
function getOctokit(
  token: string,
  options?: OctokitOptions,
  ...additionalPlugins: OctokitPlugin[]
): InstanceType<typeof GitHub>;

The returned Octokit client includes:

REST API access: Complete GitHub REST API via octokit.rest.*
GraphQL API access: GitHub GraphQL API via octokit.graphql()
Pagination support: Automatic pagination handling
Proxy support: Automatic proxy configuration for enterprise environments
Type safety: Full TypeScript support with proper type definitions

GitHub Actions Context

Access to GitHub Actions environment and webhook payload information.

const context: Context;

class Context {
  /** Webhook payload object that triggered the workflow */
  payload: WebhookPayload;
  
  /** GitHub event name (e.g., 'push', 'pull_request') */
  eventName: string;
  
  /** Git SHA of the commit */
  sha: string;
  
  /** Git reference (branch or tag) */
  ref: string;
  
  /** Workflow name */
  workflow: string;
  
  /** Action name */
  action: string;
  
  /** Actor (user) who triggered the action */
  actor: string;
  
  /** Job identifier */
  job: string;
  
  /** Run attempt number */
  runAttempt: number;
  
  /** Run number */
  runNumber: number;
  
  /** Run ID */
  runId: number;
  
  /** GitHub API URL */
  apiUrl: string;
  
  /** GitHub server URL */
  serverUrl: string;
  
  /** GitHub GraphQL URL */
  graphqlUrl: string;
  
  /** Get issue/PR information from context */
  get issue(): { owner: string; repo: string; number: number };
  
  /** Get repository owner and name from context */
  get repo(): { owner: string; repo: string };
}

GitHub Class (Direct Usage)

Extended Octokit class that can be used directly for advanced configurations.

/**
 * Extended Octokit class with REST endpoint methods and pagination plugins
 * Available via import from '@actions/github/lib/utils'
 */
const GitHub: typeof Octokit & {
  plugin: (...plugins: OctokitPlugin[]) => typeof GitHub;
  defaults: (options: OctokitOptions) => typeof GitHub;
};

This class is pre-configured with:

REST endpoint methods via @octokit/plugin-rest-endpoint-methods
Pagination support via @octokit/plugin-paginate-rest
Default proxy and base URL configuration

Utility Functions

Advanced utilities for custom Octokit configuration.

/**
 * Convenience function to correctly format Octokit options
 * @param token - The repo PAT or GITHUB_TOKEN
 * @param options - Optional Octokit configuration options
 * @returns Formatted options for Octokit constructor with proper auth handling
 */
function getOctokitOptions(
  token: string,
  options?: OctokitOptions
): OctokitOptions;

/**
 * Default Octokit configuration with proxy settings and base URL
 * Includes automatic proxy agent setup and GitHub API base URL configuration
 */
const defaults: OctokitOptions;

Types

interface PayloadRepository {
  [key: string]: any;
  full_name?: string;
  name: string;
  owner: {
    [key: string]: any;
    login: string;
    name?: string;
  };
  html_url?: string;
}

interface WebhookPayload {
  [key: string]: any;
  repository?: PayloadRepository;
  issue?: {
    [key: string]: any;
    number: number;
    html_url?: string;
    body?: string;
  };
  pull_request?: {
    [key: string]: any;
    number: number;
    html_url?: string;
    body?: string;
  };
  sender?: {
    [key: string]: any;
    type: string;
  };
  action?: string;
  installation?: {
    id: number;
    [key: string]: any;
  };
  comment?: {
    id: number;
    [key: string]: any;
  };
}

// Re-exported from @octokit/core and related packages
interface OctokitOptions {
  auth?: string | AuthInterface;
  userAgent?: string;
  previews?: string[];
  baseUrl?: string;
  log?: LogInterface;
  request?: RequestParameters;
  timeZone?: string;
  [key: string]: any;
}

interface OctokitPlugin {
  (octokit: Octokit, options: OctokitOptions): void | {
    [key: string]: any;
  };
}

interface AuthInterface {
  (...args: unknown[]): Promise<{
    type: string;
    token: string;
    tokenType?: string;
    [key: string]: unknown;
  }>;
}

interface LogInterface {
  debug: (message: string, ...additionalInfo: unknown[]) => void;
  info: (message: string, ...additionalInfo: unknown[]) => void;
  warn: (message: string, ...additionalInfo: unknown[]) => void;
  error: (message: string, ...additionalInfo: unknown[]) => void;
}

interface RequestParameters {
  method?: string;
  url?: string;
  headers?: { [key: string]: string };
  body?: string;
  request?: {
    agent?: unknown;
    fetch?: unknown;
    signal?: unknown;
    timeout?: number;
  };
}

Common Usage Patterns

Using with Webhook Events

import { context, getOctokit } from "@actions/github";

if (context.eventName === 'push') {
  const octokit = getOctokit(process.env.GITHUB_TOKEN!);
  
  // Access push event payload
  const commits = context.payload.commits;
  
  // Create comment on commit
  await octokit.rest.repos.createCommitComment({
    ...context.repo,
    commit_sha: context.sha,
    body: `Processed ${commits.length} commits`
  });
}

Plugin Extension

import { GitHub, getOctokitOptions } from "@actions/github/lib/utils";
import { enterpriseServer220Admin } from "@octokit/plugin-enterprise-server";
import * as core from "@actions/core";

// Create extended GitHub class with additional plugins
const ExtendedOctokit = GitHub.plugin(enterpriseServer220Admin);

// Create instance with proper token and options
const myToken = core.getInput('myToken');
const octokit = new ExtendedOctokit(getOctokitOptions(myToken));

// Now has enterprise admin APIs available
await octokit.rest.enterpriseAdmin.createUser({
  login: "testuser",
  email: "testuser@test.com",
});

Direct GitHub Class Usage

import { GitHub, defaults } from "@actions/github/lib/utils";

// Use GitHub class directly with custom options
const octokit = new GitHub({
  auth: `token ${process.env.GITHUB_TOKEN}`,
  userAgent: 'MyAction/1.0.0',
  ...defaults // Include default proxy and base URL settings
});

const repo = await octokit.rest.repos.get({
  owner: 'actions',
  repo: 'toolkit'
});

Error Handling

import { RequestError } from "@octokit/request-error";

try {
  const { data } = await octokit.rest.repos.get({
    owner: context.repo.owner,
    repo: context.repo.repo
  });
} catch (error) {
  if (error instanceof RequestError) {
    console.error(`GitHub API error: ${error.status} - ${error.message}`);
  } else {
    console.error('Unexpected error:', error);
  }
}