GitHub Script: Mastering Octokit

"If YAML is the skeleton of your automation, GitHub Script is the brain. It turns a boring pipeline into a smart agent."

Standard GitHub Actions are great for "Running a command." But what if you want to say: "If the PR has a label 'Urgent', find the senior engineer who is currently online and comment on their latest task"?

• You can't do that with simple YAML.
• You need JavaScript.

GitHub Script (actions/github-script) allows you to write real Node.js code directly inside your workflow file. It gives you an already-authenticated Octokit client to talk to the GitHub API. This 1,500+ word guide explores the "Programmable Pipeline" of 2026.

1. What is Octokit? (The GitHub SDK)

Octokit is the official suite of libraries for the GitHub API.

• It handles Authentication (using the automatic ${{ secrets.GITHUB_TOKEN }}).
• It handles Rate Limiting (so you don't get banned).
• It provides TypeScript types for every reaction, comment, and repo setting.

2. Basic Syntax: The github-script Action

- name: Add a Welcome Comment
  uses: actions/github-script@v7
  with:
    script: |
      github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body: 'Welcome to the TopicTrick project! 👋'
      })

Architecture Note: Notice the github.rest object. You have full access to every part of the GitHub API (Issues, PRs, Projects, Actions) as if you were writing a stand-alone Node app.

3. The context Object: Knowing your World

The github-script action provides a context variable. It tells your script:

• context.payload: Exactly what happened (Who pushed, what was the message?).
• context.sha: The unique fingerprint of the code.
• context.actor: The username of the person who triggered the action.

4. Advanced Case: The "Smart Reviewer"

Imagine you want to automatically assign a PR to someone based on which FILES were changed.

const changedFiles = await github.rest.pulls.listFiles({
  owner: context.repo.owner,
  repo: context.repo.repo,
  pull_number: context.payload.pull_request.number
});

const isDatabaseChange = changedFiles.data.some(f => f.filename.includes('sql/'));
if (isDatabaseChange) {
  await github.rest.issues.addLabels({
    issue_number: context.payload.pull_request.number,
    owner: context.repo.owner,
    repo: context.repo.repo,
    labels: ['DB-Review-Needed']
  });
}

The Benefit: This replaces "Human manual work" with "Machine precision." Your senior engineers only get pinged when there is a real database change to review.

5. Security: The GITHUB_TOKEN limitation

By default, the script uses a "Temporary Token" that only works for the current repo.

• If your script needs to "Create a Repository" or "Invite a User to the Org," it will fail.
• You must create a Personal Access Token (PAT) or a GitHub App and pass it as the github-token input.

Summary: The Scripting Checklist

1. Use Context: Don't hardcode repo names; use context.repo.owner.
2. Await Everything: GitHub API calls are asynchronous. Don't forget await!
3. Labeling: Use the script to automatically label PRs based on file paths.
4. Logging: Use console.log() inside the script to debug your logic in the Actions tab.
5. Small is Better: If your script is more than 50 lines, move it to a separate .js file and call it from the YAML.

GitHub Script turns your repo into a Living Agent. By mastering the Octokit API and the logic of the context object, you gain the ability to automate the "Boring" parts of engineering so you can focus on the "Hard" parts. You graduate from "Managing a pipeline" to "Architecting an Autonomous Workforce."

Frequently Asked Questions

Q: What is github-script and what can you do with it in a workflow? actions/github-script lets you write JavaScript directly in a workflow step with full access to the Octokit REST and GraphQL clients, the workflow context, and Node.js core modules — no separate action or API token setup needed. Use it to: create or update issues and comments, add labels to PRs, post workflow summaries, query repository data, or call any GitHub API endpoint without building a custom action.

Q: What is Octokit and how does it relate to the GitHub API? Octokit is GitHub's official JavaScript client library for the REST API and GraphQL API. It handles authentication, request retries, pagination, and response parsing. The @octokit/rest package provides a typed interface for every REST endpoint. In github-script, Octokit is pre-injected as the github parameter — you call github.rest.issues.create({...}) directly without instantiating a client or managing tokens.

Q: How do you add a comment to a pull request using github-script? Use the github.rest.issues.createComment method (GitHub treats PR comments as issue comments): await github.rest.issues.createComment({ owner: context.repo.owner, repo: context.repo.repo, issue_number: context.issue.number, body: 'Your comment text here' }). Run this in a step with uses: actions/github-script@v7 and your JavaScript in the script: key. The GITHUB_TOKEN is automatically available with write permissions if you set permissions: pull-requests: write on the job.

Part of the GitHub Mastery Course — engineering the brain.