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.
Topics on this page
Section titled “Topics on this page”| 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. |
Workflows
Section titled “Workflows”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.
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 testThe 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
permissionsat the top of every workflow and widen per job only where needed (for examplepackages: write). pull_request_targetruns 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 installin CI drifts. Usenpm ciso the lockfile decides the versions.
Secrets and variables
Section titled “Secrets and variables”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.
Self-hosted runners
Section titled “Self-hosted runners”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):
./config.sh --url https://github.com/orders-portal/orders-portal \ --token <REGISTRATION_TOKEN> --labels linux,x64,db-access --ephemeralsudo ./svc.sh install # run as a systemd service on Linuxsudo ./svc.sh startjobs: 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.
Publishing packages
Section titled “Publishing packages”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.
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_TOKENcan 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.
Webhooks
Section titled “Webhooks”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: truetampered body: falsemissing header: falsePitfalls:
- 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-Deliveryto ignore duplicates, especially after redeliveries. - Ignore the legacy header.
X-Hub-Signatureuses SHA-1 and exists for compatibility; always check the SHA-256 header.
Choosing between them
Section titled “Choosing between them”| 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 |
Interview questions
Section titled “Interview questions”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/.
Related pages
Section titled “Related pages”- GitHub administration overview
- GitHub repository governance: rulesets and required status checks.
- Tags, hooks and commit conventions: tag-triggered releases.
- GitLab runners, CI/CD variables and webhooks: the GitLab equivalents.
- GitHub overview