How to pass variables safely to github-script?

Use environment variables on the action step and reference them with process.env, as the README recommends to avoid script injection. For example, set env: TITLE: ${{ github.event.pull_request.title }} and access it in the script to safely handle inputs.

github-script or using curl in GitHub Actions?

github-script is better for complex logic and direct API interactions with built-in authentication, while curl is simpler for one-off requests but requires manual token handling and parsing. github-script's octokit client also supports pagination and GraphQL natively.

Can I use TypeScript with github-script?

Not directly; you need to compile TypeScript to JavaScript first or use jsDoc for type hints as mentioned in the README. This adds a build step, making it less convenient for inline scripting compared to pure JavaScript.

How to run an external JavaScript file in github-script?

Use the require function with a relative path after checking out the repository with actions/checkout, as shown in the examples. Pass github and context as arguments to your external function for access to API and workflow data.

What are the retry options in github-script?

Configure retries and exempt status codes via inputs; by default, it uses exponential backoff and doesn't retry on 400, 401, etc., based on the octokit/plugin-retry.js plugin. This helps with transient failures but requires explicit setup in the workflow YAML.

How to handle errors in github-script scripts?

Use try-catch blocks in your JavaScript and leverage the core toolkit for logging or setting failures, but error handling is manual. The retry configuration can help with API errors, but script logic errors need custom implementation.

github-script

MITTypeScriptv9.0.0

A GitHub Action that enables scripting the GitHub API directly in JavaScript within workflows.

GitHub

What is github-script?

GitHub Script is a GitHub Action that allows developers to write and execute JavaScript scripts directly within their GitHub Actions workflows. It provides a pre-authenticated Octokit client and workflow context, enabling seamless interaction with the GitHub API for tasks like issue management, pull request automation, and repository operations. It solves the problem of needing external scripts or complex setup to automate GitHub platform interactions.

Target Audience

Developers and DevOps engineers using GitHub Actions who need to automate GitHub platform interactions, such as managing issues, pull requests, or repository data directly within their workflows.

Value Proposition

Developers choose GitHub Script because it eliminates the overhead of setting up authentication and API clients, allowing them to write quick, inline scripts with immediate access to GitHub's API and workflow context. Its integration with the GitHub Actions ecosystem and support for npm modules make it a versatile tool for custom automation.

Overview

Write workflows scripting the GitHub API in JavaScript

Use Cases

Best For

Automating issue or pull request comments based on events

Related Projects

Community-curated · Updated weekly · 100% open source

Found a gem we're missing?

Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.

Submit a project Star on GitHub

4.9k stars554 forks0 contributors

Applying labels to issues or pull requests dynamically

Running custom GraphQL queries against the GitHub API

Integrating npm packages for advanced workflow logic

Executing shell commands within a JavaScript context

Retrieving and processing workflow context data

Not Ideal For

Teams managing complex, multi-repository automations that require reusable, version-controlled scripts outside of workflow files
Projects needing strict type safety and extensive unit testing, as it relies on inline JavaScript without built-in TypeScript support
Use cases where low-latency or high-throughput API calls are critical, due to performance limits of shared GitHub Actions runners
Organizations preferring fully declarative infrastructure-as-code over imperative scripting for all automation tasks

Pros & Cons

Pros

Instant API Authentication

Provides a pre-authenticated octokit client with built-in pagination, eliminating the need for manual token setup or external API calls, as shown in the README's examples for issue comments and labels.

Integrated Workflow Context

Automatically injects the workflow run context, including event payload and repository details, making it easy to access relevant data without parsing environment variables manually.

Modular Script Support

Allows requiring local JavaScript files and npm packages installed in the workflow, enabling complex logic and dependency management, as demonstrated with external file imports and execa usage.

Configurable Output and Retry

Supports result encoding as JSON or strings and includes retry logic with exponential backoff for failed API requests, improving reliability for automation tasks.

Cons

Frequent Breaking Changes

Major version updates (e.g., V5 to V8) introduce breaking API changes, such as method restructuring from github.issues to github.rest.issues, requiring script adjustments and testing.

Security Vulnerabilities Risk

The README warns about script injection risks when passing inputs via expressions, necessitating careful use of environment variables to avoid exploits, which adds complexity.

Limited Maintenance and Contributions

The project explicitly states it is not taking contributions, relying on GitHub's internal resources, which may slow down bug fixes and feature updates compared to community-driven actions.

Frequently Asked Questions

Home

GitHub Actions

checkout

Action for checking out a repo

Stars7,801

Forks2,463

Last commit2 months ago

cache

Cache dependencies and build outputs in GitHub Actions

Stars5,359

Forks1,526

Last commit10 days ago

upload-artifact

`@actions/upload-artifact` is an official GitHub Action that allows developers to upload files, directories, or files matching wildcard patterns as artifacts from their workflow runs. These artifacts are stored by GitHub and can be downloaded later or used by other jobs in the same workflow, facilitating data persistence and sharing across CI/CD steps. ## Key Features - **Flexible Path Specification** — Upload individual files, entire directories, or use wildcard patterns and exclusions to select specific files. - **Performance and Control** — Manually adjust compression levels for speed or size, and customize behavior when no files are found. - **Artifact Management** — Set custom retention periods, overwrite existing artifacts, and include or exclude hidden files from uploads. - **Output Integration** — Provides artifact IDs, URLs, and digests as outputs for use in subsequent steps or with the GitHub REST API. - **Immutable Archives** — Each upload creates a unique, immutable artifact, preventing accidental corruption from concurrent modifications. ## Philosophy The action is designed to be a reliable, performant, and secure method for persisting workflow data, with sensible defaults that prioritize safety (like excluding hidden files) while offering granular control for advanced use cases.

Stars4,041

Forks1,044

Last commit10 days ago

download-artifact

The `@actions/download-artifact` action enables GitHub Actions workflows to retrieve stored artifacts from workflow runs. It provides flexible options for downloading single or multiple artifacts, filtering by patterns, and accessing artifacts across different repositories and runs. ## Key Features - **Single Artifact Download** — Download a specific artifact by name or unique ID to a specified directory. - **Bulk Artifact Retrieval** — Download all artifacts from a run, with options to merge them into a single directory or keep them separate. - **Cross-Repository Access** — Download artifacts from other repositories or workflow runs using a GitHub token with appropriate permissions. - **Pattern Filtering** — Use glob patterns to download only matching artifacts, useful in multi-architecture build scenarios. - **Flexible Output Control** — Choose whether to automatically decompress artifacts or maintain them as-is for manual handling. - **File Permission Preservation** — Supports workflows that require maintaining executable permissions via tar archives. ## Philosophy The action is designed to be a reliable, configurable tool for artifact retrieval within GitHub's ecosystem, prioritizing compatibility with the platform's artifact system and providing clear, predictable behavior for common use cases.

Stars1,823

Forks695

Last commit1 month ago