Workflow Triggers, Filters, Expressions, Contexts, Variables, Inputs, and Outputs: Configuration, Design Choices, and Tradeoffs

1. Event trigger versus manual/reusable/external invocation

Choose a trigger by asking who owns the cause. If source change should always validate itself, use a repository event such as push or pull_request. If a human operator should decide when to run, use workflow_dispatch with a typed input schema. If another workflow owns the orchestration, use workflow_call. If an external system owns the cause, repository_dispatch can represent that event—but its payload is external input and the run still uses the workflow on the default branch.

2. Path filters versus in-job conditional logic

Scheduler filters prevent the run from being created. In-job conditions create the run and then skip selected jobs/steps. The former can reduce noise/compute; the latter leaves visible evidence and lets you publish a stable check name. That difference matters when branch protection requires a check.

Do not optimize Actions minutes by weakening the observability contract. First design the required evidence, then avoid unnecessary jobs within that contract.

3. vars versus env versus inputs versus secrets

“Not printed” does not make an env or vars value secret. Conversely, “stored in secrets” does not make arbitrary execution safe: code that can read a secret can intentionally exfiltrate it. Secret availability and runner/code trust must be designed together.

4. Outputs versus artifacts: metadata contract or file transfer?

Outputs are small strings attached to steps/jobs/reusable workflows and evaluated as part of the run graph. They are ideal for a version, digest, Boolean-like decision, artifact identifier, or generated name. Artifacts are stored files with retention, download, integrity, and permission concerns. Do not encode a binary or large JSON report into an output because it avoids learning artifact handling.

5. Typed inputs are UX and policy, not authorization

A choice input reduces typo space; a Boolean avoids string truthiness ambiguity; an environment input can select a GitHub environment. But input type does not authorize the action. Authorization comes from who may trigger the workflow, repository/environment policy, job permissions, and external-service identity. A caller who can choose production still must not automatically gain deployment authority.

on:
  workflow_dispatch:
    inputs:
      target:
        type: choice
        options: [staging, production]
        required: true

jobs:
  deploy:
    # Input chooses intent; environment policy governs authority.
    environment: ${{ inputs.target }}
    runs-on: ubuntu-latest

Environment governance is covered in Chapter 19. Here the key principle is separation: parameters describe requested behavior; permissions/protection rules decide whether the behavior is allowed.

6. Reusable workflows are versioned APIs

workflow_call turns a workflow file into a callable interface. Inputs and outputs are a schema. A caller can reference a reusable workflow from the same repository or an allowed external repository according to GitHub’s access rules. Treat the reusable workflow reference as a supply-chain dependency: production callers should deliberately select and review the version/reference they execute.

# Called workflow
on:
  workflow_call:
    inputs:
      test_level:
        type: string
        required: true
    outputs:
      report_id:
        value: ${{ jobs.validate.outputs.report_id }}

Do not use secrets as ordinary inputs. workflow_call has a separate secret contract, and nested reusable workflows require explicit forwarding/inheritance choices.

7. Worked scenario: Atlas Edge validation and release planning

Atlas Edge has a required PR validation, an optional expensive integration suite, a nightly dependency report, and a reusable release-preflight unit. Choose the control for each requirement.

Cost: avoid trigger storms and unnecessary jobs. Compatibility: verify GHES version before assuming newest GitHub.com syntax such as current typed-input or schedule features. Security: inputs and event payloads do not become trusted because they arrive through a structured context.

8. Anti-patterns and safer replacements

• Anti-pattern: store a token in vars. Replace: secret or short-lived OIDC/App token, least privilege.
• Anti-pattern: use path filters on a required workflow without testing check behavior. Replace: stable check-producing workflow and conditional expensive jobs.
• Anti-pattern: parse a Boolean input as the string "true" everywhere. Replace: use typed inputs context.
• Anti-pattern: pass large build results as outputs. Replace: artifact/package mechanisms with explicit identity.
• Anti-pattern: let an external dispatch payload choose a shell command. Replace: allowlist typed event names/values and map them to fixed commands.

9. Lesson summary

The design goal is not fewer YAML lines; it is a smaller number of explicit contracts. Event contracts govern activation, variable classes govern configuration ownership, secret boundaries govern sensitive data, and output contracts govern forward data flow. A production workflow should make each contract reviewable without executing it.

Knowledge check

Further reading — current official GitHub sources

• GitHub Docs — Workflow syntax
• GitHub Docs — Events that trigger workflows
• GitHub Docs — Expressions
• GitHub Docs — Contexts reference
• GitHub Docs — Variables
• GitHub Docs — Pass job outputs
• GitHub Docs — Script injections
• GitHub Docs — Secure use reference
• GitHub CLI — gh workflow run
• GitHub CLI — gh run list
• GitHub Docs — Reuse workflows
• GitHub Docs — Variables concepts
• GitHub Docs — Artifacts concepts