Skip to content

GitHub Actions and automation: secrets to webhooks

GitHub Actions is GitHub’s built-in automation platform: YAML workflows in your repository run jobs on GitHub-hosted or self-hosted machines when something happens, such as a push, a pull request, a schedule, a release or a manual trigger. Most teams use it for CI/CD, but the same building blocks publish packages, label issues and react to events. When an external system needs to know what happened in a repository, webhooks deliver the events over HTTP instead.

This page follows an invented OrdersPortal Node.js service from its first CI workflow to production concerns: storing secrets and configuration, running jobs on your own machines, publishing an npm package to GitHub Packages, and receiving webhook events safely. Facts were checked against the GitHub Docs source in November 2026; the action versions (actions/checkout@v6, actions/setup-node@v7) are the ones the docs use. Workflows are fragments to commit to .github/workflows/; the webhook verifier was run with Node.js 22.

Topic Use it when
Workflows You want CI to build and test every push and pull request.
Secrets and variables Jobs need credentials or environment-specific configuration.
Self-hosted runners Jobs need your network, hardware or software.
Publishing packages You publish npm packages or container images next to the code.
Webhooks An external service must react to repository events.

A workflow is a YAML file in .github/workflows/. The on key lists the events that trigger it; jobs run in parallel by default (use needs to order them); each job has runs-on to pick a runner and a list of steps, each either a shell command (run) or a reusable action (uses). The permissions key limits what the automatically created GITHUB_TOKEN can do in that workflow, which is the first security setting to get right. Thousands of ready-made actions are published on GitHub Marketplace; pin third-party actions to a full commit SHA so a moved tag cannot change what runs.

.github/workflows/ci.yml
name: CI
on:
push:
branches: [main]
pull_request:
permissions:
contents: read
jobs:
build-and-test:
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [22, 24]
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v7
with:
node-version: ${{ matrix.node-version }}
cache: npm
- run: npm ci
- run: npm test

The job name build-and-test (with the matrix value) is what you list as a required status check in a ruleset; see repository governance.

Pitfalls:

  • Default token permissions can be broad. Set permissions at the top of every workflow and widen per job only where needed (for example packages: write).
  • pull_request_target runs with secrets. It runs in the context of the base branch with access to secrets; never check out and run untrusted pull request code in it.
  • npm install in CI drifts. Use npm ci so the lockfile decides the versions.

Secrets hold sensitive values (API keys, deployment credentials); variables hold non-sensitive configuration (a region, a feature flag, a URL). Both can be defined at organization, repository and environment level under Settings > Secrets and variables > Actions, and read in workflows through the secrets and vars contexts. When the same name exists at several levels, the most specific one wins: environment, then repository, then organization.

Environments (for example staging and production) add deployment protection: environment secrets are only released to jobs that reference the environment, and protection rules such as required reviewers or a wait timer pause the job until approved. Environments are available for public repositories on all current plans and for private repositories on Pro, Team and Enterprise; on Free, Pro and Team, required reviewers and wait timers are only available for public repositories.

# .github/workflows/deploy.yml (fragment)
jobs:
deploy:
runs-on: ubuntu-latest
environment: production
permissions:
contents: read
steps:
- uses: actions/checkout@v6
- name: Deploy OrdersPortal
run: ./scripts/deploy.sh "$DEPLOY_REGION"
env:
DEPLOY_REGION: ${{ vars.DEPLOY_REGION }}
DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}

Limits from the docs: up to 1,000 organization secrets, 100 repository secrets and 100 environment secrets, each up to 48 KB; up to 1,000 organization variables, 500 repository variables and 100 environment variables. GitHub masks registered secrets in logs, and echo "::add-mask::$VALUE" masks a value created during the run. Where the cloud provider supports it, OpenID Connect (OIDC) lets a job request short-lived cloud credentials instead of storing long-lived keys as secrets.

Pitfalls:

  • Secrets are not passed to workflows triggered from forks (except a read-only GITHUB_TOKEN). Fork pull requests cannot deploy, by design.
  • Secrets cannot be used directly in if: conditions. Map them to an environment variable first and test that.
  • Masking is not a guarantee. Structured values (JSON blobs) and transformed output (base64, URL-encoded) can slip past log redaction; store one value per secret.

GitHub-hosted runners are fresh virtual machines per job. A self-hosted runner is a machine you operate that runs the runner application and picks up jobs for a repository, an organization or (on Enterprise) an enterprise. Use one when jobs need private network access, special hardware such as GPUs, licensed software, or cheaper capacity at scale. You are responsible for the operating system, tools and security patches; the runner application updates itself.

Register a runner from Settings > Actions > Runners > New self-hosted runner, which shows download commands and a short-lived registration token. --labels adds custom labels that workflows can target, and --ephemeral makes the runner take exactly one job and then unregister, which is the basis for clean, autoscaled runners (fragment; the token is a placeholder):

Terminal window
./config.sh --url https://github.com/orders-portal/orders-portal \
--token <REGISTRATION_TOKEN> --labels linux,x64,db-access --ephemeral
sudo ./svc.sh install # run as a systemd service on Linux
sudo ./svc.sh start
jobs:
integration-tests:
runs-on: [self-hosted, linux, x64, db-access]

A job runs on a runner that has all the listed labels. For large fleets on Kubernetes, Actions Runner Controller (ARC) scales ephemeral runners automatically.

Pitfalls:

  • Do not use self-hosted runners for public repositories. Anyone can open a pull request that runs code on your machine. GitHub’s guidance is that self-hosted runners should almost never be used for public repositories.
  • Persistent runners leak state between jobs. Files, credentials and caches left by one job are visible to the next. Prefer ephemeral runners, or at least separate runners per trust level.
  • Organization runners need runner groups. Without restricting which repositories can use a runner, any repository in the organization can send jobs to it.

GitHub Packages hosts packages next to the source: a container registry (ghcr.io) plus npm, Maven, Gradle, NuGet and RubyGems registries. Packages can inherit the access of the repository they are linked to, and workflows can publish with the built-in GITHUB_TOKEN when the job has packages: write. npm packages on GitHub Packages must be scoped (@orders-portal/pricing) and use lowercase names.

.github/workflows/publish.yml
name: Publish package
on:
release:
types: [published]
jobs:
publish:
runs-on: ubuntu-latest
permissions:
contents: read
packages: write
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v7
with:
node-version: 24
registry-url: https://npm.pkg.github.com
scope: '@orders-portal'
- run: npm ci
- run: npm publish
env:
NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

setup-node writes an .npmrc that points the scope at npm.pkg.github.com and reads the token from NODE_AUTH_TOKEN. Consumers configure the same scope mapping in their own .npmrc and authenticate with a token that can read packages; never commit that token. Container images follow the same pattern with docker login ghcr.io -u ${{ github.actor }} and GITHUB_TOKEN.

Pitfalls:

  • Publishing to another repository needs a different token. GITHUB_TOKEN can publish only to packages linked to the workflow’s repository.
  • Versions are immutable. You cannot republish the same version; bump it (see tags and versions).
  • Private packages need auth to install. CI jobs in other repositories need read access granted on the package.

A webhook sends an HTTP POST with a JSON payload to your URL when selected events happen (push, pull request, issues, workflow runs and many more). Create one under Settings > Webhooks > Add webhook: the payload URL, content type application/json, a secret, and the events you need (avoid “Send me everything”). Each delivery carries headers such as X-GitHub-Event (the event name), X-GitHub-Delivery (a unique ID) and, when a secret is set, X-Hub-Signature-256: sha256= followed by the HMAC-SHA256 hex digest of the raw request body, keyed with the secret.

Your receiver must verify that signature before trusting the payload, using a constant-time comparison, and must answer with a 2xx status within 10 seconds or GitHub records the delivery as failed. Do the real work asynchronously. The verifier below uses the test vector from GitHub’s documentation; save it as verify-github.mjs and run node verify-github.mjs with Node.js 22:

import { createHmac, timingSafeEqual } from "node:crypto";
// Verify the X-Hub-Signature-256 header GitHub sends with each delivery.
export function isValidGitHubSignature(secret, rawBody, signatureHeader) {
if (!signatureHeader?.startsWith("sha256=")) return false;
const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(signatureHeader);
return a.length === b.length && timingSafeEqual(a, b);
}
// Test vector published in the GitHub docs ("Validating webhook deliveries").
const secret = "It's a Secret to Everybody";
const body = "Hello, World!";
const header = "sha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17";
console.log("valid delivery:", isValidGitHubSignature(secret, body, header));
console.log("tampered body: ", isValidGitHubSignature(secret, body + "!", header));
console.log("missing header:", isValidGitHubSignature(secret, body, undefined));

Output:

valid delivery: true
tampered body: false
missing header: false

Pitfalls:

  • Verify the raw bytes. Parsing and re-serializing JSON before computing the HMAC changes the body and every signature fails.
  • Deliveries can repeat. Use X-GitHub-Delivery to ignore duplicates, especially after redeliveries.
  • Ignore the legacy header. X-Hub-Signature uses SHA-1 and exists for compatibility; always check the SHA-256 header.
Need Use
React to an event inside GitHub (build, test, label, release) A workflow triggered by that event
Run jobs inside your network or on special hardware Self-hosted runners, ideally ephemeral
Notify an external system about repository events A webhook with a secret
Store credentials for jobs Environment secrets, or OIDC where supported
Share build outputs with other projects GitHub Packages

What is GITHUB_TOKEN and how should you scope it? A token GitHub creates for each workflow run, valid only for that run and that repository. Set permissions at workflow level to the minimum (often contents: read) and grant extra scopes per job, such as packages: write for publishing.

How do environment secrets differ from repository secrets? Environment secrets are only available to jobs that reference the environment, and only after the environment’s protection rules (required reviewers, wait timer, branch restrictions) pass. Repository secrets are available to every workflow in the repository, except those triggered from forks.

Why are self-hosted runners risky on public repositories? Any pull request can run arbitrary code on the runner, which may have network access, credentials or leftover state from previous jobs. Use GitHub-hosted runners for public repositories, and ephemeral runners with restricted runner groups otherwise.

How do you verify a GitHub webhook? Compute HMAC-SHA256 over the raw body with the shared secret, prefix sha256=, and compare with X-Hub-Signature-256 using a constant-time comparison. Reject on mismatch, then process asynchronously and answer 2xx within 10 seconds.

Senior scenario: a security review finds a long-lived cloud deploy key stored as a repository secret and used by every workflow. How do you redesign it? Replace the key with OIDC federation so the deploy job requests short-lived credentials scoped to the repository, branch and environment. Move deployment into a production environment with required reviewers and a branch restriction to main, set permissions minimally with id-token: write only on the deploy job, and rotate and delete the old key. Pin third-party actions to commit SHAs and review workflow changes through CODEOWNERS for .github/workflows/.