Skip to main content

Chapter 12: GitHub Actions & CI/CD Workflows

Part IV: Developer Tooling & Workflows Prerequisites: Chapter 9: GitHub CLI (gh) for Enterprise GH-100 Exam Mapping: Domain 6 (Manage GitHub Actions -- 16%) Verified: 2026-02-01 against official documentation

1. Introduction​

Learning Objectives​

After completing this chapter, you will be able to:

  • Design GitHub Actions workflows using jobs, steps, and runner configurations
  • Deploy and manage self-hosted runners for enterprise environments
  • Create reusable workflows and composite actions for organizational consistency
  • Configure Actions policies, secrets management, and environment protection rules at enterprise scale
  • Distribute starter workflows and internal actions across an enterprise

Exam Domain Coverage​

DomainTopics in This Chapter
D6: Manage GitHub Actions (16%)Workflows, self-hosted runners, reusable workflows, secrets, enterprise policies, starter workflows

Chapter Overview​

GitHub Actions is the native Continuous Integration and Continuous Delivery (CI/CD) platform built into GitHub. For enterprise organizations with 50 or more developers, Actions provides far more than simple build automation -- it is the engine that powers code quality gates, security scanning, deployment pipelines, and increasingly, agentic workflows where Copilot coding agents submit and validate their own pull requests.

This chapter covers the full scope of GitHub Actions from an enterprise administration perspective. You will learn the foundational concepts -- workflows, jobs, steps, and runners -- and then progress into enterprise-specific concerns: self-hosted runner fleets, reusable workflow libraries, secrets management at scale, environment protection rules, and the policy controls that enterprise and organization owners use to govern Actions usage across hundreds of repositories.

Domain 6 of the GH-100 exam accounts for 16% of the total score, making it the second-largest domain. The exam tests your ability to manage Actions at the enterprise level -- not just write workflow files. This chapter directly prepares you for those questions.

See Chapter 9: GitHub CLI (gh) for Enterprise for the gh commands used throughout this chapter. See Chapter 1: Enterprise Subscription & Environment Setup for the enterprise account hierarchy that governs Actions policies.


2. Theory & Deep Dive​

2.1 Actions Fundamentals: The Building Blocks​

GitHub Actions uses a hierarchy of four core concepts that map directly to your CI/CD pipeline design.

Workflows are the top-level automation unit. A workflow is defined by a YAML (YAML Ain't Markup Language) file stored in the .github/workflows/ directory of a repository. Workflows are triggered by events -- push, pull request, schedule, manual dispatch, or webhook events. A single repository can contain multiple workflows, each serving a different purpose (build, test, deploy, security scan).

Jobs are the units of execution within a workflow. Each job runs on a separate runner and, by default, jobs execute in parallel. You can create dependencies between jobs using the needs keyword to enforce sequential execution. Each job has its own isolated filesystem and environment.

Steps are the individual tasks within a job. Steps execute sequentially in the order they are defined. A step can either run a shell command (using run) or invoke a published action (using uses). Steps within the same job share a filesystem, allowing earlier steps to produce artifacts that later steps consume.

Runners are the compute environments where jobs execute. GitHub provides hosted runners (Linux, Windows, macOS) managed by GitHub, or organizations can deploy self-hosted runners on their own infrastructure. The choice of runner type is one of the most consequential decisions for enterprise Actions deployments.

Here is a minimal workflow that demonstrates all four concepts:

# .github/workflows/ci.yml
name: CI Pipeline

on:
pull_request:
branches: [main]

jobs:
build:
runs-on: ubuntu-latest # Runner
steps: # Steps
- uses: actions/checkout@v4 # Step 1: Action
- name: Install dependencies # Step 2: Shell command
run: npm ci
- name: Run tests
run: npm test

lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run linter
run: npm run lint

deploy:
needs: [build, lint] # Job dependency
runs-on: ubuntu-latest
steps:
- name: Deploy to staging
run: echo "Deploying..."

Key workflow syntax elements for the exam:

ElementPurposeExample
onEvent triggerpush, pull_request, schedule, workflow_dispatch
runs-onRunner selectionubuntu-latest, windows-latest, self-hosted
needsJob dependencyneeds: [build, test]
usesInvoke an actionuses: actions/checkout@v4
runExecute a shell commandrun: npm test
envSet environment variablesenv: NODE_ENV: production
ifConditional executionif: github.event_name == 'push'
strategy.matrixRun across combinationsmatrix: { node: [18, 20, 22] }

Enterprise Scenario: A 120-developer e-commerce company has 45 repositories. Their platform team defines a standard CI workflow triggered on every pull request. The workflow runs three parallel jobs -- unit tests, integration tests, and static analysis -- before a sequential deployment job. Using needs to enforce the gate ensures no code reaches staging without passing all quality checks.

2.2 GitHub-Hosted vs. Self-Hosted Runners​

The runner decision is central to enterprise Actions planning.

GitHub-Hosted Runners are virtual machines (VMs) managed by GitHub. Each job receives a fresh VM that is destroyed after the job completes. GitHub-hosted runners support Ubuntu Linux, Windows Server, and macOS. They come pre-installed with common development tools and have direct internet access.

Advantages of GitHub-hosted runners:

  • Zero infrastructure management
  • Clean environment for every job (no state leakage between builds)
  • Automatic updates to runner software and pre-installed tools
  • Available immediately with no setup

Limitations of GitHub-hosted runners:

  • Fixed hardware specifications (you can select larger runners on GitHub Enterprise Cloud)
  • Cannot access private network resources without additional configuration
  • Usage is metered and billed per minute
  • Limited customization of the software environment

GitHub-Hosted Larger Runners are available on GitHub Enterprise Cloud (GHEC). Enterprise and organization owners can configure runners with 4 to 64 vCPUs, up to 256 GB RAM (Random Access Memory), and optional GPU (Graphics Processing Unit) support. Larger runners can be assigned static IP address ranges, enabling IP allowlisting for firewall-protected resources.

Self-Hosted Runners are machines that you provision, configure, and maintain. You install the GitHub Actions runner application, which connects to GitHub and polls for jobs. Self-hosted runners can be physical machines, virtual machines, containers, or cloud instances.

Advantages of self-hosted runners:

  • Full control over hardware, operating system, and installed software
  • Access to private network resources (databases, internal APIs, artifact registries)
  • No per-minute billing (you pay only for your own infrastructure)
  • Persistent environments with pre-installed dependencies and caches

Limitations of self-hosted runners:

  • You are responsible for security patching, updates, and monitoring
  • Risk of state leakage between jobs if not properly isolated
  • Requires network configuration to communicate with GitHub (HTTPS outbound on port 443)
  • Must not be used on public repositories due to the risk of arbitrary code execution from untrusted forks

Enterprise Scenario: A healthcare technology company with 80 developers needs their CI/CD pipeline to access a private container registry and an internal compliance scanning service behind a corporate firewall. GitHub-hosted runners cannot reach these resources. The DevOps team deploys a fleet of 12 self-hosted runners on their Azure Virtual Network (VNet), registers them in runner groups, and assigns those groups to specific organizations that need internal network access.

Runner Groups allow enterprise and organization owners to organize self-hosted runners and control which repositories or organizations can use them. At the enterprise level, you create runner groups and assign them to specific organizations. At the organization level, you can further restrict groups to specific repositories.

# List runner groups at the enterprise level
gh api /enterprises/ENTERPRISE/actions/runner-groups --jq '.runner_groups[].name'

# Create a runner group restricted to specific organizations
gh api --method POST /enterprises/ENTERPRISE/actions/runner-groups \
-f name="production-runners" \
-f visibility="selected" \
--jq '.id'

Runner Labels are tags attached to runners that workflows use for targeting. Every self-hosted runner automatically receives three default labels: self-hosted, the operating system (e.g., linux), and the architecture (e.g., x64). You can add custom labels to match your organizational taxonomy:

# Add a custom label to a self-hosted runner
# First, get the runner ID
gh api /orgs/ORG/actions/runners --jq '.runners[] | "\(.id) \(.name)"'

# Then add labels
gh api --method POST /orgs/ORG/actions/runners/RUNNER_ID/labels \
-f 'labels[]=gpu' \
-f 'labels[]=high-memory'

Workflows target labeled runners:

jobs:
ml-training:
runs-on: [self-hosted, linux, gpu]
steps:
- name: Train model
run: python train.py

2.3 Reusable Workflows and Composite Actions​

As organizations scale beyond a handful of repositories, duplicating workflow logic becomes a maintenance burden. GitHub provides two mechanisms for sharing automation logic: reusable workflows and composite actions.

Reusable Workflows are complete workflow files that other workflows can call using the workflow_call trigger. A reusable workflow defines its own jobs and steps, and the calling workflow treats it as a single job. Reusable workflows support inputs and secrets, allowing callers to parameterize the shared logic.

A reusable workflow is defined in a repository (typically a central .github or shared-workflows repository):

# org-shared/.github/workflows/standard-ci.yml
name: Standard CI

on:
workflow_call:
inputs:
node-version:
description: 'Node.js version to use'
required: false
type: string
default: '20'
secrets:
NPM_TOKEN:
required: true

jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ inputs.node-version }}
- run: npm ci
env:
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
- run: npm test

A calling workflow invokes it:

# my-service/.github/workflows/ci.yml
name: CI
on:
pull_request:
branches: [main]

jobs:
standard-ci:
uses: org-shared/.github/workflows/standard-ci.yml@main
with:
node-version: '22'
secrets:
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

Constraints on reusable workflows:

  • A reusable workflow can call another reusable workflow, but nesting is limited to a maximum depth of four levels
  • A calling workflow can invoke up to 20 reusable workflows
  • Environment variables set in an env context in the caller are not propagated to the called workflow
  • The reusable workflow must be in a public repository, an internal repository accessible to the calling repository, or the same repository

Composite Actions package multiple steps into a single action that can be referenced with uses. Unlike reusable workflows (which define entire jobs), composite actions define steps that run within the caller's job. This makes them ideal for sharing sequences of setup or teardown steps.

# .github/actions/setup-project/action.yml
name: 'Setup Project'
description: 'Install dependencies and configure environment'
inputs:
node-version:
description: 'Node.js version'
required: false
default: '20'
runs:
using: 'composite'
steps:
- uses: actions/setup-node@v4
with:
node-version: ${{ inputs.node-version }}
- run: npm ci
shell: bash
- run: npm run build
shell: bash

Usage in a workflow:

jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: ./.github/actions/setup-project
with:
node-version: '22'
- run: npm test
FeatureReusable WorkflowsComposite Actions
ScopeEntire jobsSteps within a job
Runner selectionEach job picks its own runnerInherits caller's runner
Secrets handlingExplicit secrets parameterInherits caller's context
Nesting depthUp to 4 levelsNo specific limit
Use caseStandardize full CI/CD pipelinesShare setup/teardown sequences

Enterprise Scenario: A platform engineering team at a 200-developer company maintains a shared-workflows repository containing three reusable workflows: standard-ci.yml, security-scan.yml, and deploy-to-k8s.yml. Product teams call these workflows from their repositories, ensuring every service follows the same quality and security gates. When the platform team updates the scanning tool version, the change propagates to all 90 repositories on their next workflow run.

2.4 Secrets Management​

GitHub Actions provides encrypted secrets at three scope levels: organization, repository, and environment. Secrets are encrypted at rest and are masked in workflow logs.

Organization Secrets are defined at the organization level and can be shared with all repositories, private repositories only, or a selected list of repositories. Organization owners manage these secrets from the organization settings.

# Set an organization-level secret available to selected repositories
gh secret set NPM_TOKEN --org my-org --visibility selected \
--repos "service-a,service-b,service-c"

Repository Secrets are scoped to a single repository. Any workflow in the repository can access these secrets.

# Set a repository-level secret
gh secret set DATABASE_URL --repo my-org/my-service

Environment Secrets are scoped to a specific deployment environment (e.g., staging, production). A job must reference the environment to access its secrets. Environment secrets override repository secrets of the same name when the environment is active.

# Set an environment-level secret
gh secret set AWS_ACCESS_KEY_ID --repo my-org/my-service --env production

Secret precedence: When secrets with the same name exist at multiple levels, the most specific scope wins. Environment secrets override repository secrets, which override organization secrets.

OpenID Connect (OIDC) for cloud authentication: For enterprise deployments to cloud providers such as Microsoft Azure, Amazon Web Services (AWS), or Google Cloud Platform (GCP), GitHub Actions supports OIDC-based authentication. Instead of storing long-lived cloud credentials as secrets, workflows request short-lived tokens from the cloud provider using GitHub's OIDC identity. This eliminates the risk of leaked static credentials.

jobs:
deploy:
runs-on: ubuntu-latest
permissions:
id-token: write # Required for OIDC
contents: read
steps:
- uses: actions/checkout@v4
- uses: azure/login@v2
with:
client-id: ${{ secrets.AZURE_CLIENT_ID }}
tenant-id: ${{ secrets.AZURE_TENANT_ID }}
subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
- run: az webapp deploy --name my-app --src-path ./dist
shell: bash

Third-party vault integration: For organizations with existing secrets management infrastructure (HashiCorp Vault, Azure Key Vault, AWS Secrets Manager), Actions workflows can retrieve secrets dynamically at runtime rather than storing them in GitHub. This approach centralizes secret rotation and audit logging.

Enterprise Scenario: A financial services company with 150 developers uses Azure Key Vault as their centralized secrets store. Their GitHub Actions workflows authenticate to Azure using OIDC (no stored credentials), then retrieve database connection strings and API keys from Key Vault at runtime. This approach satisfies their compliance requirement that secrets must be rotated every 90 days without modifying any GitHub repository settings.

2.5 Environment Protection Rules​

GitHub deployment environments provide gating mechanisms that control when and how deployments proceed. These are critical for enterprise change management processes.

Required Reviewers: You can designate up to six users or teams as required reviewers for an environment. When a workflow job references a protected environment, it pauses and waits for approval from one of the designated reviewers before proceeding. This enforces the separation of duties principle -- the developer who wrote the code is not necessarily the person who approves the deployment.

Wait Timer: A configurable delay (0 to 43,200 minutes, i.e., up to 30 days) that the job must wait after approval before executing. Wait timers are useful for scheduled maintenance windows or cooldown periods between deployments.

Deployment Branches and Tags: You can restrict which branches or tags are allowed to deploy to an environment. For example, limiting a production environment to only the main branch prevents feature branches from accidentally deploying to production.

Custom Deployment Protection Rules: GitHub supports custom protection rules implemented as GitHub Apps. These allow organizations to integrate external systems (change management tools, compliance scanners, stability monitors) as deployment gates.

jobs:
deploy-production:
runs-on: ubuntu-latest
environment:
name: production
url: https://app.example.com
steps:
- uses: actions/checkout@v4
- name: Deploy to production
run: ./scripts/deploy.sh production
shell: bash

When this job runs, GitHub checks the production environment's protection rules. If required reviewers are configured, the job pauses until a reviewer approves. If a wait timer is set, the job waits the additional duration. If branch restrictions are configured, the job fails if it runs from an unauthorized branch.

Enterprise Scenario: A 75-developer SaaS (Software as a Service) company configures three environments: development (no protection), staging (requires one reviewer from the QA team), and production (requires two reviewers from the release management team, 15-minute wait timer, restricted to the main branch). This setup ensures that production deployments are reviewed, have a brief cooldown period, and can only originate from the main branch.

2.6 Actions Policies at Enterprise and Organization Levels​

Enterprise and organization owners can govern how GitHub Actions is used across their organizations and repositories. These policies are hierarchical -- enterprise policies set the ceiling, and organization policies can be equal to or more restrictive than the enterprise policy but never more permissive.

Enabling or disabling Actions: At the enterprise level, you can:

  • Allow all actions (no restrictions)
  • Allow only local actions (actions defined in the same repository)
  • Allow select actions (specify an allowlist of actions and reusable workflows)
  • Disable Actions entirely
# View current enterprise Actions permissions
gh api /enterprises/ENTERPRISE/actions/permissions \
--jq '{enabled: .enabled_organizations, allowed: .allowed_actions}'

Action allowlists: When using the "Allow select actions" policy, you can allow:

  • Actions created by GitHub (e.g., actions/checkout, actions/setup-node)
  • Actions from GitHub Marketplace verified creators
  • Specific actions by owner/repository pattern (e.g., my-org/* to allow all actions from your organization)
# Configure an organization to allow only GitHub-created and specific actions
gh api --method PUT /orgs/ORG/actions/permissions/selected-actions \
-F github_owned_allowed=true \
-F verified_allowed=true \
-f 'patterns[]=my-org/*'

Workflow permissions: You can set the default permissions granted to the GITHUB_TOKEN at the enterprise, organization, and repository levels. The principle of least privilege dictates setting the default to read-only and requiring workflows to explicitly request additional permissions.

# In a workflow file, explicitly request only needed permissions
permissions:
contents: read
pull-requests: write
issues: write

Fork pull request policies: For enterprises that use fork-based contribution models, you can control whether workflows run on pull requests from forks and whether those workflows have access to secrets. The recommended enterprise setting is to require approval for first-time contributors before their workflow runs execute.

Enterprise Scenario: An enterprise with 300 developers across five organizations sets the enterprise-level policy to "Allow select actions." They allow all actions from actions/* (GitHub-owned), their internal acme-corp/* organization, and three verified third-party actions for cloud deployments. Individual organizations cannot override this to allow arbitrary Marketplace actions, preventing supply chain attacks from unvetted third-party actions.

2.7 Starter Workflows and Internal Action Sharing​

Starter Workflows (also known as workflow templates) are pre-configured workflow files that appear in the "Actions" tab when a repository has no workflows, or when a user clicks "New workflow." Organizations can create custom starter workflows that reflect their standards and best practices.

To create an organization-level starter workflow:

  1. Create a public or internal repository named .github in the organization
  2. Add workflow template files to the workflow-templates/ directory
  3. Add a companion properties file (JSON) for each workflow template
# .github/workflow-templates/org-ci.yml
name: Organization CI
on:
pull_request:
branches: [$default-branch]

jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Build
run: echo "Add your build commands here"
- name: Test
run: echo "Add your test commands here"
// .github/workflow-templates/org-ci.properties.json
{
"name": "Organization CI",
"description": "Standard CI pipeline for all organization repositories",
"iconName": "octicon-check-circle",
"categories": ["continuous-integration"]
}

When developers in the organization create a new workflow, your organization's starter workflows appear alongside GitHub's built-in templates, pre-populated with your preferred configuration.

Internal Action Sharing: By default, actions in private repositories cannot be used by workflows in other repositories. For enterprise organizations, you can configure a private or internal repository to allow its actions and reusable workflows to be used by other repositories within the same organization or enterprise.

In the repository settings under Actions > General, set the access policy:

  • "Not accessible" (default for private repos)
  • "Accessible from repositories in the 'ORGANIZATION' organization"
  • "Accessible from repositories in the 'ENTERPRISE' enterprise"
# Configure a repository to share its actions with the organization
gh api --method PUT /repos/ORG/shared-actions/actions/permissions/access \
-f access_level="organization"

Enterprise Scenario: The platform engineering team at a 100-developer company maintains an internal repository acme-corp/shared-actions containing composite actions for Docker builds, Kubernetes deployments, and security scanning. They set the repository's access level to "enterprise" so all five organizations in the enterprise can use these actions. They also publish three starter workflows in acme-corp/.github/workflow-templates/ for Node.js services, Python services, and infrastructure-as-code repositories. When any developer creates a new repository and navigates to the Actions tab, they see the organization's templates as recommended starting points.

2.8 Workflow Security Best Practices for Enterprises​

Enterprise-scale Actions deployments must address several security vectors:

Pin action versions by SHA: Instead of referencing actions by tag (which can be moved), pin to the full commit SHA to prevent supply chain attacks:

# Preferred: pin by SHA
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

# Acceptable but less secure: pin by tag
- uses: actions/checkout@v4

Least-privilege GITHUB_TOKEN: Set the default workflow permission to read-only at the organization level. Require individual workflow files to declare the specific permissions they need.

Audit logging: GitHub Enterprise Cloud streams Actions-related audit log events including workflow runs, secret access, runner registration, and policy changes. Forward these to your Security Information and Event Management (SIEM) system for monitoring. See Chapter 6: Security & Audit for enterprise audit log configuration.

Dependency review in CI: Use the actions/dependency-review-action in pull request workflows to block PRs that introduce known vulnerabilities.

jobs:
dependency-review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/dependency-review-action@v4
with:
fail-on-severity: moderate

3. Diagrams​

GitHub Actions Workflow Execution Model​

flowchart TD
A[Developer pushes code<br/>or opens pull request] --> B{Event matches<br/>workflow trigger?}
B -->|No| Z[No workflow runs]
B -->|Yes| C[GitHub queues<br/>workflow run]
C --> D[Job 1: Build<br/>runs-on: ubuntu-latest]
C --> E[Job 2: Lint<br/>runs-on: ubuntu-latest]
D --> D1[Step 1: actions/checkout]
D1 --> D2[Step 2: npm ci]
D2 --> D3[Step 3: npm test]
E --> E1[Step 1: actions/checkout]
E1 --> E2[Step 2: npm run lint]
D3 --> F{Both jobs<br/>succeeded?}
E2 --> F
F -->|No| G[Workflow fails<br/>PR blocked by status check]
F -->|Yes| H[Job 3: Deploy<br/>needs: build, lint]
H --> H1{Environment<br/>protection rules?}
H1 -->|Required reviewers| I[Pause for approval]
I --> H2[Step 1: Deploy to staging]
H1 -->|No protection| H2
H2 --> J[Workflow completes<br/>successfully]

style A fill:#2d333b,stroke:#539bf5,color:#adbac7
style D fill:#2d333b,stroke:#57ab5a,color:#adbac7
style E fill:#2d333b,stroke:#57ab5a,color:#adbac7
style H fill:#2d333b,stroke:#e5534b,color:#adbac7
style J fill:#2d333b,stroke:#57ab5a,color:#adbac7
style G fill:#2d333b,stroke:#e5534b,color:#adbac7

Figure 1: GitHub Actions workflow execution model showing event triggers, parallel job execution, job dependencies via needs, environment protection rule gates, and workflow outcome. Jobs 1 and 2 run in parallel; Job 3 waits for both to succeed and may require reviewer approval before deploying.

Enterprise Runner Architecture​

flowchart LR
subgraph GitHub Cloud
GH[GitHub.com<br/>Actions Service]
end

subgraph Enterprise Network
subgraph Runner Group: Production
R1[Runner 1<br/>linux, x64, production]
R2[Runner 2<br/>linux, x64, production]
end
subgraph Runner Group: Development
R3[Runner 3<br/>linux, x64, dev]
R4[Runner 4<br/>windows, x64, dev]
end
DB[(Internal<br/>Database)]
REG[(Private Container<br/>Registry)]
end

GH -->|HTTPS port 443<br/>outbound only| R1
GH -->|HTTPS port 443<br/>outbound only| R2
GH -->|HTTPS port 443<br/>outbound only| R3
GH -->|HTTPS port 443<br/>outbound only| R4
R1 --> DB
R1 --> REG
R2 --> DB
R2 --> REG

style GH fill:#2d333b,stroke:#539bf5,color:#adbac7
style R1 fill:#2d333b,stroke:#57ab5a,color:#adbac7
style R2 fill:#2d333b,stroke:#57ab5a,color:#adbac7
style R3 fill:#2d333b,stroke:#e5c07b,color:#adbac7
style R4 fill:#2d333b,stroke:#e5c07b,color:#adbac7

Figure 2: Enterprise self-hosted runner architecture. Runners initiate outbound HTTPS connections to GitHub (no inbound firewall rules required). Production runners access internal databases and private registries. Runner groups segregate production and development workloads, with organization-level policies controlling which repositories can use each group.

Secrets Scope Hierarchy​

flowchart TD
ORG[Organization Secrets<br/>Broadest scope] --> REPO[Repository Secrets<br/>Override org secrets]
REPO --> ENV[Environment Secrets<br/>Override repo secrets<br/>Most specific scope]

ORG -.->|Available to all or<br/>selected repositories| REPO
REPO -.->|Available to all<br/>workflows in repo| ENV
ENV -.->|Available only when<br/>job references environment| DEPLOY[Deployment Job]

style ORG fill:#2d333b,stroke:#539bf5,color:#adbac7
style REPO fill:#2d333b,stroke:#57ab5a,color:#adbac7
style ENV fill:#2d333b,stroke:#e5534b,color:#adbac7
style DEPLOY fill:#2d333b,stroke:#e5c07b,color:#adbac7

Figure 3: Secrets scope hierarchy. Environment secrets have the highest precedence and are only available when a job explicitly references the environment, providing an additional access control layer for sensitive production credentials.


4. Summary​

Key Takeaways:

  • GitHub Actions workflows consist of four building blocks: workflows (YAML files triggered by events), jobs (parallel execution units), steps (sequential tasks within a job), and runners (compute environments)
  • GitHub-hosted runners provide zero-maintenance environments; self-hosted runners provide network access, custom hardware, and cost control for enterprise workloads -- but must never be used on public repositories
  • Runner groups and labels allow enterprise administrators to organize runner fleets and control which organizations and repositories can target specific runners
  • Reusable workflows standardize entire CI/CD pipelines across repositories; composite actions share step sequences within a job -- both are essential for organizations with 50+ repositories
  • Secrets exist at three scopes -- organization, repository, and environment -- with environment secrets having the highest precedence; OIDC authentication eliminates the need for long-lived cloud credentials
  • Environment protection rules (required reviewers, wait timers, branch restrictions) enforce change management processes and separation of duties for production deployments
  • Enterprise Actions policies set the ceiling for what actions are allowed; organization policies can further restrict but never exceed the enterprise policy; the recommended default is to allow only GitHub-owned actions and your own internal actions
  • Starter workflows in the organization's .github repository provide templates that guide developers toward approved patterns; internal repository sharing enables cross-organization action reuse
  • Security best practices include pinning actions by SHA, defaulting GITHUB_TOKEN to read-only, streaming audit logs, and integrating dependency review into CI pipelines

What's Next: See Chapter 13: Coding Agent for how GitHub Copilot coding agents use GitHub Actions workflows to build, test, and validate their own code changes autonomously.


5. Hands-On Assignment​

Prerequisites Check: Before starting this lab, ensure you have completed:

  • A working GitHub Enterprise Cloud environment (Chapter 1: Enterprise Subscription & Environment Setup)
  • Organization structure configured (Chapter 7: Organization Design & Team Architecture)
  • At least one repository with write access

Lab: Build an Enterprise CI/CD Pipeline with GitHub Actions​

Objective: Create a CI/CD pipeline for an enterprise application that uses reusable workflows, environment protection rules, secrets management, and a deployment gate.

Prerequisites:

  • A GitHub Enterprise Cloud organization (or GHEC trial from Chapter 1)
  • GitHub CLI (gh) version 2.40 or later
  • A repository with a simple web application (Node.js, Python, or any language with a test suite)
  • Organization owner or repository admin permissions

Assignment:

  1. Create a reusable workflow in a shared repository that runs linting, tests, and a security scan
  2. Create a calling workflow in your application repository that invokes the reusable workflow
  3. Configure two deployment environments: staging (no reviewers) and production (one required reviewer, branch restricted to main)
  4. Add an organization-level secret for a shared API key and a repository-level environment secret for production credentials
  5. Configure the organization's Actions policy to allow only GitHub-created actions and actions from your organization
  6. Verify the entire pipeline by opening a pull request and observing the workflow execution, environment gates, and deployment

Expected Outcome: A pull request triggers the CI pipeline via the reusable workflow. After merging to main, the deployment workflow targets staging automatically and then pauses for manual approval before deploying to production.

Validation Criteria:

  • The reusable workflow is callable from the application repository
  • Environment protection rules are enforced (production requires approval)
  • Organization secrets are accessible in the workflow
  • The organization's Actions policy restricts third-party action usage
  • The workflow run log shows all three secrets scopes being used correctly (values masked)

6. Step-by-Step Walkthrough​

This section provides a guided solution for the hands-on assignment above. If you completed the assignment independently, you can skip this section or use it to verify your approach.

Step 1: Create the Shared Workflows Repository​

Create a repository in your organization to host reusable workflows.

# Create the shared workflows repository
gh repo create my-org/shared-workflows --internal \
--description "Organization-wide reusable GitHub Actions workflows"

Clone the repository and create the reusable workflow:

# Clone the repository
gh repo clone my-org/shared-workflows

Create the file .github/workflows/standard-ci.yml in the shared-workflows repository with the following content:

# shared-workflows/.github/workflows/standard-ci.yml
name: Standard CI

on:
workflow_call:
inputs:
node-version:
description: 'Node.js version'
required: false
type: string
default: '20'
run-security-scan:
description: 'Run security scanning step'
required: false
type: boolean
default: true
secrets:
NPM_TOKEN:
required: false

jobs:
lint-and-test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: ${{ inputs.node-version }}
- name: Install dependencies
run: npm ci
shell: bash
env:
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
- name: Lint
run: npm run lint
shell: bash
- name: Test
run: npm test
shell: bash

security-scan:
if: ${{ inputs.run-security-scan }}
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/dependency-review-action@v4
if: github.event_name == 'pull_request'
with:
fail-on-severity: moderate

Push the reusable workflow:

# Stage and commit
git add .github/workflows/standard-ci.yml
git commit -m "Add standard CI reusable workflow"
git push origin main

Configure the repository to share its workflows with the organization:

# Allow the organization to access this repository's workflows
gh api --method PUT /repos/my-org/shared-workflows/actions/permissions/access \
-f access_level="organization"

Step 2: Create the Application Workflow​

In your application repository, create a workflow that calls the reusable workflow and adds deployment jobs.

# Navigate to your application repository
gh repo clone my-org/my-app

Create the file .github/workflows/ci-cd.yml:

# my-app/.github/workflows/ci-cd.yml
name: CI/CD Pipeline

on:
push:
branches: [main]
pull_request:
branches: [main]

permissions:
contents: read
pull-requests: write

jobs:
# Call the organization's standard CI workflow
ci:
uses: my-org/shared-workflows/.github/workflows/standard-ci.yml@main
with:
node-version: '22'
run-security-scan: true
secrets:
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

# Deploy to staging after CI passes
deploy-staging:
needs: ci
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
environment:
name: staging
url: https://staging.example.com
steps:
- uses: actions/checkout@v4
- name: Deploy to staging
run: |
echo "Deploying to staging environment..."
echo "Using staging API endpoint: ${{ vars.API_ENDPOINT }}"
shell: bash

# Deploy to production with approval gate
deploy-production:
needs: deploy-staging
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
environment:
name: production
url: https://app.example.com
steps:
- uses: actions/checkout@v4
- name: Deploy to production
run: |
echo "Deploying to production environment..."
echo "Using production API endpoint: ${{ vars.API_ENDPOINT }}"
shell: bash

Push the workflow:

git add .github/workflows/ci-cd.yml
git commit -m "Add CI/CD pipeline with reusable workflow and deployment environments"
git push origin main

Step 3: Configure Deployment Environments​

Create the staging and production environments using the GitHub API (Application Programming Interface):

# Create staging environment (no protection rules)
gh api --method PUT /repos/my-org/my-app/environments/staging

# Create production environment with protection rules
gh api --method PUT /repos/my-org/my-app/environments/production \
-f 'reviewers[][type]=User' \
-F "reviewers[][id]=$(gh api /users/YOUR_USERNAME --jq '.id')" \
-f 'deployment_branch_policy[protected_branches]=false' \
-f 'deployment_branch_policy[custom_branch_policies]=true'

# Restrict production to the main branch only
gh api --method POST /repos/my-org/my-app/environments/production/deployment-branch-policies \
-f name="main" -f type="branch"

Step 4: Configure Secrets at Multiple Scopes​

# Organization-level secret: shared NPM token
# (available to selected repositories)
gh secret set NPM_TOKEN --org my-org --visibility selected \
--repos "my-app,shared-workflows"

# Repository-level secret: application-specific key
gh secret set APP_SECRET_KEY --repo my-org/my-app

# Environment-level secret: production database URL
gh secret set DATABASE_URL --repo my-org/my-app --env production

# Environment-level secret: staging database URL
gh secret set DATABASE_URL --repo my-org/my-app --env staging

Step 5: Configure Organization Actions Policy​

Restrict the organization to allow only GitHub-created actions and internal actions:

# Set organization Actions permissions
gh api --method PUT /orgs/my-org/actions/permissions \
-f enabled_repositories="all" \
-f allowed_actions="selected"

# Configure the allowlist
gh api --method PUT /orgs/my-org/actions/permissions/selected-actions \
-F github_owned_allowed=true \
-F verified_allowed=false \
-f 'patterns[]=my-org/*'

Set the default GITHUB_TOKEN permission to read-only:

# Set default token permissions to read-only for the organization
gh api --method PUT /orgs/my-org/actions/permissions/workflow \
-f default_workflow_permissions="read" \
-F can_approve_pull_request_reviews=false

Step 6: Verify the Pipeline​

Create a feature branch and open a pull request to trigger the workflow:

# Create a feature branch
git checkout -b feature/test-pipeline

# Make a small change
echo "// test change" >> src/index.js
git add src/index.js
git commit -m "Test CI/CD pipeline"
git push origin feature/test-pipeline

# Open a pull request
gh pr create --title "Test CI/CD pipeline" \
--body "Verifying the complete CI/CD pipeline with reusable workflows and environment gates."

Monitor the workflow run:

# Watch the workflow run in real time
gh run watch

# After the run completes, view the details
gh run list --repo my-org/my-app --limit 5

After merging the pull request, verify the deployment pipeline:

# Merge the pull request
gh pr merge --squash

# Watch the deployment workflow
gh run watch

# The production deployment should be waiting for approval
gh run view --repo my-org/my-app

Expected output: The workflow pauses at the deploy-production job with a "Waiting for review" status. Navigate to the workflow run in the browser to approve the deployment, or have a designated reviewer approve it.

Verification​

Confirm the full pipeline is operational:

# List environments and their protection rules
gh api /repos/my-org/my-app/environments --jq '.environments[] | {name, protection_rules}'

# Verify organization Actions policy
gh api /orgs/my-org/actions/permissions --jq '{enabled: .enabled_repositories, allowed: .allowed_actions}'

# List secrets at each scope
gh secret list --org my-org
gh secret list --repo my-org/my-app
gh secret list --repo my-org/my-app --env production
gh secret list --repo my-org/my-app --env staging

7. Q&A -- Chapter Review​

Instructions: Select the best answer for each question. Answers and explanations follow after all questions.

Question 1​

An enterprise administrator wants to ensure that all organizations can only use GitHub-created actions and actions from internal repositories. Where should this policy be configured?

  • A) In each repository's .github/workflows/ directory
  • B) At the enterprise level under Actions permissions
  • C) In the organization's .github repository
  • D) At the repository level under Settings > Actions

Question 2​

A workflow has three jobs: build, test, and deploy. The deploy job should only run after both build and test complete successfully. Which keyword achieves this?

  • A) depends-on: [build, test]
  • B) after: [build, test]
  • C) needs: [build, test]
  • D) requires: [build, test]

Question 3​

Which type of runner should an enterprise avoid using on public repositories due to security risks?

  • A) GitHub-hosted runners
  • B) GitHub-hosted larger runners
  • C) Self-hosted runners
  • D) macOS runners

Question 4​

An organization has a secret named API_KEY at both the repository level and the production environment level. When a workflow job references the production environment, which secret value is used?

  • A) The repository-level secret always takes precedence
  • B) The environment-level secret overrides the repository-level secret
  • C) The workflow fails due to a naming conflict
  • D) The organization-level secret takes precedence over both

Question 5​

A platform team wants to share a standard CI pipeline that defines its own jobs and runner selections. Which mechanism should they use?

  • A) Composite actions
  • B) Starter workflows
  • C) Reusable workflows with workflow_call trigger
  • D) Repository templates

Question 6​

What is the maximum nesting depth for reusable workflows calling other reusable workflows?

  • A) 2 levels
  • B) 3 levels
  • C) 4 levels
  • D) Unlimited

Question 7​

An organization wants to eliminate long-lived cloud credentials stored as GitHub secrets. Which approach should they adopt for authenticating to cloud providers?

  • A) Store credentials in repository environment variables
  • B) Use OpenID Connect (OIDC) tokens for short-lived authentication
  • C) Hard-code credentials in the workflow YAML file
  • D) Use personal access tokens with no expiration

Question 8​

Where should an organization place custom starter workflow templates so they appear when developers create new workflows?

  • A) In the .github/workflows/ directory of each repository
  • B) In the workflow-templates/ directory of the organization's .github repository
  • C) In the enterprise account's settings page
  • D) In a repository named starter-workflows in the organization

Question 9​

A deployment environment is configured with a required reviewer and a 30-minute wait timer. What happens when a workflow job references this environment?

  • A) The job runs immediately and the reviewer is notified after completion
  • B) The job pauses for reviewer approval, then waits an additional 30 minutes after approval before executing
  • C) The job waits 30 minutes, then requests reviewer approval
  • D) The wait timer and reviewer approval run concurrently, and the job proceeds after both are satisfied

Question 10​

An enterprise administrator sets the default GITHUB_TOKEN permission to "read" at the organization level. A workflow in a repository within this organization declares permissions: { contents: write }. What happens?

  • A) The workflow is blocked because the organization default is read-only
  • B) The workflow's explicit permission declaration overrides the organization default, granting write access
  • C) The workflow runs but the token has only read access
  • D) The repository must be added to an allowlist before write permissions are granted

Answer Key​

QAnswerExplanation
1BEnterprise-level Actions permissions set the ceiling for all organizations. When configured at the enterprise level to allow only GitHub-created actions and specific patterns, no organization can override this to allow additional third-party actions. This is the recommended approach for large enterprises.
2CThe needs keyword creates a dependency between jobs. needs: [build, test] ensures the deploy job only runs after both build and test complete successfully. The other options are not valid GitHub Actions syntax.
3CSelf-hosted runners must not be used on public repositories because anyone can fork the repository, modify the workflow, and execute arbitrary code on the self-hosted runner. GitHub-hosted runners are isolated and destroyed after each job, making them safe for public repositories.
4BWhen secrets exist at multiple scopes with the same name, the most specific scope wins. Environment secrets override repository secrets, which in turn override organization secrets. This allows teams to use different credentials per environment.
5CReusable workflows with the workflow_call trigger define complete jobs with their own runner selections and steps. Composite actions only define steps within a caller's job. Starter workflows are templates, not callable pipelines.
6CReusable workflows can nest up to 4 levels deep. A reusable workflow can call another reusable workflow, which can call another, up to four levels. Beyond this depth, the workflow call fails.
7BOpenID Connect (OIDC) allows GitHub Actions to request short-lived tokens from cloud providers, eliminating the need to store long-lived credentials as secrets. The workflow presents a JWT signed by GitHub, and the cloud provider exchanges it for a temporary access token.
8BOrganization-level starter workflows must be placed in the workflow-templates/ directory of the organization's .github repository. Each template needs a corresponding .properties.json file that provides metadata (name, description, icon, categories).
9BEnvironment protection rules are evaluated sequentially. The job first pauses for reviewer approval. Once a reviewer approves, the wait timer begins. After the 30-minute wait timer elapses, the job's steps execute. The timer is applied after approval, not before or concurrently.
10BSetting the default GITHUB_TOKEN permission to read-only at the organization level changes only the default. Individual workflows can still request elevated permissions using the permissions key in their workflow file. The explicit declaration in the workflow overrides the default. This approach ensures workflows must consciously opt in to elevated permissions.