Skip to main content

GitHub Actions

This document provides a quick glance at GitHub Actions and DevSecOps. Read more to deepen your understanding of how to automate security within your delivery pipeline. Before reading this document please read Git and DevSecOps CI CD Pipeline

CI/CD is like an automated assembly line in a factory. DevOps is the culture that keeps that line running smoothly. DevSecOps is like adding high-tech security cameras and quality checks at every single point on that assembly line, rather than just checking the final product at the exit gate. This ensures that what you build is not just fast, but also "bulletproof."

1. GitHub - The Infrastructure for Your Code​

GitHub is more than just a place to save files; it is the Single Source of Truth for source code history and security policy.

  • The Repository (.git): This is your website's "History Book." Every line of code ever written is tracked here.

  • Branching Strategy: You should have a main branch (Production) and develop or feature branches.

  • Never code directly on main. Use Pull Requests (PRs) so your team can review the code before it goes live.

  • Pull Requests (PR): This is the "Security Gate." It’s where you compare new code with the old code. This is exactly where GitHub Actions will run its automated scans.

  • GitHub Secrets: Located in Settings > Secrets. This is a specialized, encrypted vault for your Website's API keys (Stripe, AWS, Database passwords). Once saved, no one can see them not even you.

2. GitHub Actions: The Automation Engine​

Think of GitHub Actions as a "Smart Assistant" living inside your repository. Previously, if you wanted to build and secure your website, you had to hire a different assistant (Jenkins), give them a separate office (Server), and constantly sync them with your code. GitHub Actions is like having an assistant who already knows your code, works for free (mostly), and never sleeps.

A workflow is defined in a .yml file inside the .github/workflows/ folder. It consists of:

  • Events (The Trigger):

  • push: Runs every time you save code to GitHub.

  • pull_request: Runs when you want to merge code (Perfect for Security Scans).

  • schedule: Runs on a "Cron" (e.g., every midnight) to check for new security bugs in your old code.

  • Jobs (The Department):

  • Jobs are groups of tasks. You might have a test job and a deploy job.

  • Parallel execution: By default, all jobs run at the same time to save time.

  • Sequential execution: You can make deploy wait for test using the needs keyword.

  • Runners (The Computer):

  • GitHub provides a fresh, clean Virtual Machine (VM) for every job.

  • Most websites use ubuntu-latest. Because it's a fresh VM every time, it's highly secure no "leftover" data from previous builds can leak.

  • Steps & Actions (The Tasks):

  • Steps are individual commands (e.g., npm install).

  • Actions are pre-written "Lego blocks" from the GitHub Marketplace. Instead of writing code to log into AWS, you use a verified aws-actions/configure-aws-credentials.

**TopicShort NotesOfficial Doc****What is GitHub Actions?**It is an Event-Driven automation platform. This means it waits for an "Event" (like a code push, a new release, or a specific time) and then triggers a "Workflow." It uses YAML a DevSecOps view, it's the "Engine" that runs your security scanners.Understanding ActionsWhy GitHub Actions was CreatedTo solve "Integration Hell." Before 2018, connecting GitHub to third-party CI tools was a security risk because you had to share access tokens. By building it natively, GitHub made automation Safer and Faster. It removed the "Plugin management" headache found in tools like Jenkins.About ActionsPricing & QuotasPublic repos are 100% Free. Private repos get 2,000 mins/month (Free plan). From a DevSecOps view, monitor your "Build Minutes" because complex security scans (like DAST) can consume minutes quickly. Use efficient caching to save money.GHA BillingShift-Left Security with GHAUse Pull Request Decorations. When a developer opens a PR, GHA runs a scan and leaves a comment directly on the code line that has a security bug. This is the ultimate "Hero" move fixing the bug before it even enters the main branch.Code SecurityThe "Marketplace" Security RiskThe GHA Marketplace has thousands of actions. Warning: Anyone can publish an action. A DevSecOps engineer only uses "Verified Creator" actions or pins actions to a specific Commit SHA to prevent "Supply Chain Attacks."Using Marketplace Actions**Policy as Code (Governance)**Write rules in GHA that say: "If the security scan finds a 'Critical' bug, the 'Merge' button must be disabled." This turns security policy into un-skippable code. No more "Requesting permission" from the security team; the pipeline decides.Security PoliciesAuditability & ComplianceGHA stores logs for up to 90 days. Action LogsOIDC for Cloud SecurityGone are the days of storing AWS/Azure keys in GitHub Secrets. Use OIDC (OpenID Connect). GHA can "Talk" to AWS directly using short-lived tokens. Even if someone hacks your GitHub, there are no permanent keys to steal.About OIDCEnvironment ProtectionFor your website, you can create a "Production" environment in GHA. You can set a rule that only the CTO or Lead Developer can approve a deployment to this environment. This adds a "Human-in-the-loop" security layer.Using Environments

3. Core Concepts & Architecture​

Think of the Workflow as your "Project Plan." The Event is the "Trigger". The Job is a "Department". The Runner is the "Office" where work happens, and Steps are the "Task List" on the wall.

**TopicShort NotesOfficial Doc****What is a Workflow?**A workflow is a .yml file stored in .github/workflows/ that orchestrates your entire process. separate for CI (Pull Requests), CD (Deployments), and Security Tests.Workflows**What is an Event?**Events are the "triggers when" push, pull_request, workflow_dispatch. and schedule Security Scans before merge and on your dependencies even if no code was changed.Workflow Events**What is a Job?**Jobs are group of steps. Crucially, Jobs run in parallel by default. A workflow can have many jobs like build, test, security-scan, deploy.Using Jobs**What is a Step?**Steps are the specific commands, install tools, run tests, scan code. steps must be ordered logically: 1. Checkout, 2. Lint/Build, 3. Security Scan, 4. Test. If a step fails, the job stops immediately,Workflow Steps**What is an Action?**These are reusable automation code. Instead of writing script required task use already available actions. About Actions**What is a Runner?**The server executes jobs code/pipeline. Runners can be GitHub-hosted or self-hosted depending on security and compliance needs.About RunnersGitHub-Hosted RunnersManaged by GitHub. Pros: Zero maintenance, highly secure isolation. Cons: No access to your private office network/VPN. Perfect for scanning public-facing websites.Hosted RunnersSelf-Hosted RunnersYour own servers (AWS EC2, local PC). Used when you need custom tools, private networks, or strict compliance. These are "Persistent." If a hacker compromises a job on a self-hosted runner, they might gain access to your internal network. Only use them if you need specialized hardware or private database access.Self-Hosted RunnersWorkflow Syntax & StructureEverything lives in .github/workflows/. in YAML format. Pipeline, Jobs, Steps, Actions,Workflow SyntaxJob Dependency FlowThis is the "Chain of Command." By using needs: [test, scan], you ensure that the deployment job is physically impossible to start unless both tests and scans return a "Green" status.Job DependenciesVariables and Secrets UsageUse ${{ vars.NAME }} and ${{ secrets.NAME }}. GitHub automatically masks these in logs with ***. Used to store Variables, Secrets, Tokens etc.Encrypted SecretsLeast Privilege PrincipleStandardize the permissions block at the top of your YAML. If your workflow only needs to read code, set permissions: contents: read. This prevents a compromised action from writing malicious code back into your repo.GHA PermissionsLogs & ArtifactsLogs are for "What happened," Artifacts are "What was produced" (like a .zip of your website). In DevSecOps, we upload Security Reports (SARIF files) as artifacts so they can be reviewed by the security team.Logs & Artifacts**Reusable Workflow Call (Reusability)**Instead of copying each pipeline steps and security steps into every project, create one "Gold Standard" secured workflow and "Call" it from other repos. This ensures every website in your company follows the same security rules.Reusable WorkflowsConcurrency ControlIf you push code 5 times in 1 minute, you don't want 5 deployments running at once. Use concurrency to cancel older, outdated builds, saving costs and preventing "Release Overlap" security issues.ConcurrencyRunner Group SecurityFor large teams, group your runners. You can restrict "High Security" jobs (like Production Deploy) to only run on specific, hardened runners that have no internet access.Runner Groups

  • Conditionals (if statements):

  • Note: You can run security scans only on main branch but run linter on every branch.

  • Example: if: github.event_name == 'pull_request' this saves money by not running heavy scans on every tiny commit.

  • Environment Variables vs Secrets:

  • Note: Use env for non-sensitive data (like NODE_ENV: production) and secrets for sensitive data. Mixing them is a common beginner mistake that leads to security leaks.

  • Timeout Management:

  • Note: A "Zombied" job can run for 6 hours and eat all your free credits. Always set timeout-minutes: 10 on steps and jobs. If a security scan takes longer than 10 mins, something is wrong.

  • Action Version Pinning (The Ultimate DevSecOps Move):

  • Note: Don't use actions/checkout@v4. Use actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 (the full SHA). If a hacker hijacks the v4 tag, your pipeline stays safe because the SHA never changes.

4. Events & Triggers​

Triggers are like "Sensors." A push trigger is like a sensor on the door it goes off every time someone enters. A schedule trigger is like an alarm clock it goes off at a fixed time. A workflow_dispatch is like a manual doorbell you press it yourself. In DevSecOps, we use these sensors to ensure that no "Unsafe Guest" (vulnerable code) enters our website.

TopicShort NotesOfficial Doc**push EventThe push event triggers a workflow when code is pushed to a branch. Commonly used for CI builds and basic tests. In DevSecOps, push events usually run fast checks, not heavy security scans.push Eventpull_request EventRuns workflows when a PR is opened, updated, or reopened. This is the most important DevSecOps trigger because security scans run before merge, blocking vulnerable code early.pull_requestpull_request vs pull_request_targetpull_request runs with the code from the fork (untrusted) but has no secrets access. pull_request_target runs with code from your repo (trusted) and has access to secrets. Never use pull_request_target to run build scripts from a PR, or a hacker could steal your AWS keys.PR Target SecurityBranch FiltersUse branches: [main] to ensure that deployment workflows only run on the production branch. this prevents "Shadow Deployments" from feature branches. strict scans run only on protected branches, saving cost and risk.Branch FiltersPath FiltersUse paths: ['src/**']. If you only change a README file, why run a full website build and security scan? This saves CI minutes and reduces the "Noise" for the team.Path Filterspaths-ignore Filters**paths-ignore skips workflows when only non-critical files change (docs, README). This avoids wasting CI minutes and unnecessary security scans.paths-ignoreTag-Based TriggersTrigger on tags: ['v*']. Tags are immutable (mostly). tags to trigger a "Final Production Build" where Docker images are signed and scanned for high-level vulnerabilities.Tag TriggersRelease EventsFires when a GitHub Release is created. Use this for "Post-Release" tasks like notifying the security team or generating a Software Bill of Materials (SBOM) for compliance.Release Eventsworkflow_dispatchAllows manual trigger from GitHub UI. Used for manual security scans, emergency fixes, or controlled production deployments.Manual Triggers**Scheduled Workflows (Cron)**Use schedule: - cron: '0 0 * * *' (Midnight daily). Even if you don't change your code, a library you use might get a new vulnerability today. Daily scans catch "Zero-Day" issues in your dependencies.Scheduled Events**workflow_run (Chaining)**Trigger one workflow only after another finishes. Use this to separate your "Insecure Build" from your "Secure Deploy." The Deploy workflow only triggers if the Build + Scan workflow returns "Success."Workflow Runrepository_dispatchAn "External Trigger." Use this if you want an external security tool (like a bug bounty platform) to trigger a GitHub Action when a bug is found.Repo Dispatchcheck_run & check_suiteThese triggers react to other GitHub App status checks. Useful for advanced DevSecOps integrations where you want to trigger a "Fixer Action" if a linter fails.Check Events

5. Jobs, Dependencies & Flow Control​

TopicShort NotesOfficial Doc****Parallel JobsBy default, jobs in GitHub Actions run in parallel. This saves time when jobs don’t depend on each other. In DevSecOps, you can run tests, linting, and security scans together to get faster feedback.Parallel Jobs**Sequential Jobs needs**Use needs: [job_name] to create a chain. For your website, the deploy job should always "need" the security_scan job. If the scan fails, GitHub Actions physically prevents the deploy job from even starting.Job Dependencies**Conditional Execution if**Use logic like if: github.ref == 'refs/heads/main'. ConditionsExpressions ${{ }}Expressions fetch dynamic values like branch name, event type, or job outputs. DevSecOps pipelines use expressions to change security behavior based on environment (dev vs prod).ExpressionsStatus Functionssuccess(), failure(), cancelled(), always(). Use if: failure() to trigger an "Incident Alert" (like a send notification) or specifically when a security scan finds a vulnerability.Status ChecksData Between StepsSteps share the same disk. If Step A creates a scan-results.json, Step B can read it directly. This is used to pass "Vulnerability Counts" from a scanner to a custom script that decides to fail the build.Workflow CommandsData Between JobsSince jobs run on different runners (servers), they don't share a disk. You must use outputs to pass small strings and Artifacts to pass large files (like a security report).Job OutputsFan-Out / Fan-In****Fan-out: Triggering 10 parallel scans for 10 microservices. Fan-in: A single "Gatekeeper" job that waits for all 10 to finish and creates one consolidated "Security Scorecard." decides final go/no-go for releaseMatrix StrategySecurity GatesThis is a "Stop/Go" job. It doesn't build anything; it just checks if the previous security results are clean. If the "Gate" stays red, the code stays in the repository and never touches the server.Security GuidesEnvironment ControlGitHub "Environments" (Dev/Prod) allow you to set different Secrets and Reviewers. You can force a rule that "No code goes to Prod unless the Security Lead clicks Approve."EnvironmentsFail-Fast Strategycontinue-on-error: false. If a critical security step fails, kill the whole job immediately. Do not waste a single second (or cent) continuing a compromised build.Fail-FastJob-Level PermissionsAt the top of each job, define permissions:. The scan job only needs security-events: write, while the deploy job needs contents: read. This limits the "Blast Radius."PermissionsMatrix Security TestingTest your website security against multiple Node.js versions or OS types. A vulnerability might exist in Node 18 but not in Node 20. Matrix testing catches these "Environment-specific" bugs.Matrix Jobsconcurrency LockingPrevents "Race Conditions." If two people deploy at once, the concurrency block ensures only the latest one wins, preventing the server from being in an "In-between" insecure state.ConcurrencyBuild Matrix via JSONDynamically generate your list of jobs using a JSON output from a previous job. Great for "Mono-repos" where you only want to scan the 2 folders that actually changed.Dynamic Matrix

GitHub-Hosted Runner like a "Rental Car." You use it for one trip, then return it. GitHub cleans it for the next person, and you don't worry about maintenance.

Self-Hosted Runner is like "Your Own Car." You can customize it, but you are responsible for the fuel, the locks, and the security.

6. Runners & Infrastructure​

TopicShort NotesOfficial Doc****GitHub-Hosted InternalsThese are high-security, Ephemeral Virtual Machines (VMs). Every time a job starts, GitHub gives you a fresh Ubuntu/Windows/Mac image. Once the job ends, the VM is deleted instantly. This is the Gold Standard for DevSecOps because there is no "Persistence".Hosted Runners**OS Selection (Linux vs. Others)**Linux (Ubuntu) is the "King". Most security tools (Trivy, CodeQL, Gitleaks) are optimized for Linux. It is also the cheapest. Only use Windows or Mac if you are building specific .NET or iOS apps for your website.Runner OSSelf-Hosted Runner SetupYou install a small agent on your own server (AWS, local server). It "polls" GitHub for work. Used when you need custom tools, private networks, or compliance control.Self-Hosted SetupRunner Security HardeningIf you use self-hosted runners, Never use them for public repositories. A hacker could send a Pull Request with a script that steals your server's SSH keys. Always run these inside a "Sandboxed" environment (like a Docker container or restricted VM).Hardening RunnersEphemeral Self-Hosted RunnersConfigure runner to Auto-Terminate after finishing job. This mimics GitHub-hosted behavior on your own hardware, ensuring that no secret data is left in the /tmp folder for the next job to see.Ephemeral Runners**Auto-Scaling (ARC)**Using Actions Runner Controller (ARC) with Kubernetes. This automatically creates 100 runners when the team is pushing code and scales down to 0 when no jobs. From a security view, this reduces the "Attack Surface" because servers only exist when they are needed.Autoscaling RunnersRunner Performance TuningSlow builds lead to "Security Fatigue." Use the actions/cache action to store your node_modules. A fast pipeline ensures developers actually wait for security results instead of skipping them.Runner PerformanceHandling Runner FailuresSometimes a runner crashes or runs out of disk space, timeout, or crashes. Retry Logic and ensures that a runner failure blocks the deployment. A "Failed Scan" must never be treated as a "Pass."Monitoring RunsSecrets on RunnersSecrets are provided as environment variables only when the runner starts. If using a self-hosted runner, ensure your "Cleanup" script clears the environment variables and temporary logs, otherwise the next developer might see them.Secrets SecurityTrusted vs Untrusted WorkloadsStandard Policy: Use GitHub-Hosted for all Pull Requests from external contributors. Use Self-Hosted only for internal main branch deployments where you need access to your private database or VPN.Security Guidelines**Network Isolation (VPC)**Place your self-hosted runners in a Private Subnet with no public IP. Use a NAT Gateway for outbound traffic. This ensures that even if a runner is hacked, the attacker cannot "Lateral Move" to your database servers.Network Hardening**Large Runners (GPU/RAM)**GitHub now offers "Large Runners" with up to 64-core CPUs. Useful if heavy workload high RAM to avoid "Out of Memory" crashes.About Large RunnersRunner GroupsGroup your runners into "Security Zones." You can create a "Prod-Runner-Group" that only has access to Production AWS keys and restrict it so only "Signed Workflows" can run on them.Managing GroupsJust-in-Time (JIT) TokensInstead of using long-lived runner registration tokens, use JIT tokens. These are valid for only a few minutes to register a runner, making it impossible for a stolen token to be used by a hacker later.JIT Runner Tokens

7. Build, Test & Artifact Management​

TopicShort NotesOfficial Doc****Running Shell CommandsThe run keyword is the "heart" of your script. Always use the set -e (default in GHA) which ensures the script stops immediately if any command fails. Avoid using sudo unless absolutely necessary to follow the "Least Privilege" rule.Run SyntaxBuilding Node.js AppsUse actions/setup-node. For security, use npm ci (Clean Install) instead of npm install, npm ci ensures your package-lock.json is strictly followed, preventing "Dependency Confusion" attacks where a hacker injects a fake package.Node.js GuideBuilding Java AppsUse actions/setup-java. Integrate SonarQube or Snyk directly into the Maven/Gradle build command to catch security flaws while the code is compiling.Java GuideBuilding Python AppsUse actions/setup-python. and uses pip-audit during the build to check if any of the libraries in requirements.txt have known CVEs (vulnerabilities).Python GuideRunning Unit TestsTests must run before the build is finished. If tests fail, the pipeline should stop. look for "Code Coverage" if tests only cover 10% of the code, 90% of your app could have hidden security bugs.Automating TestsTest Report HandlingDon't just run tests; visualize them. Use actions like dorny/test-reporter to show test results in the PR. This helps the security team see if security-related tests (like Auth tests) passed.Artifact StorageUploading ArtifactsUse actions/upload-artifact. An artifact is the "Verified Build." Never upload secrets or .env files as artifacts. Anyone with read access to the repo can download them.Upload ArtifactDownloading ArtifactsThe deploy job downloads the artifact from the build job. This ensures that the code you are deploying is exactly the same code that was scanned and tested. No "re-building" on the fly.Download ArtifactRetention PoliciesArtifacts eat up storage space (and money). Set retention-days: 7 for general builds, but keep security scan reports (SARIF files) for 90 days to satisfy compliance auditors.Retention PolicyBuild Once, Deploy ManyBuild one Docker image or Zip file. Scan it. Then move that same file to Staging, then to Prod. If build separately for Prod, that might accidentally introduce a bug or vulnerability that wasn't in Staging.Artifact ConceptsSecurity Gates in BuildIntegrate SAST tools like Trivy or Checkov. If the scanner finds a "High" or "Critical" vulnerability, use exit 1 to fail the build. This is the ultimate DevSecOps enforcement.Security GuidesArtifact Integrity - SigningUse tools like Cosign to "Sign" your build artifact. In the deploy stage, verify the signature. This proves the artifact wasn't tampered with while sitting in GitHub's storage.Code SecurityBuild Logs TraceabilityGitHub logs every line of the build. For auditing, these logs tell you which version of the compiler was used and which security patches were present on the runner at that time.Logs & MonitoringCaching vs Artifacts****Cache is for speeding up the build (temporary). Artifact is the result of the build (permanent for that run). Mixing them up is a common mistake. Don't cache sensitive build results.Caching DocsSBOM GenerationGenerate a Software Bill of Materials (SBOM) during the build. This is a list of every single library used in your application. It's becoming a legal requirement for security compliance.Generating SBOMs

1. Multi-Stage Builds​

If your website runs in a container, use Multi-stage builds.

  • The first stage has all the "Build Tools" (which are heavy and insecure). The second stage only copies the "Final Binary." This results in a smaller "Attack Surface" because there are no compilers or package managers in the production image.

2. Handling SARIF Files​

SARIF (Static Analysis Results Interchange Format) is the standard language for security tools.

  • Always ensure security scanners output a .sarif file. Use the github/codeql-action/upload-sarif action. This makes the security bugs show up in the "Security" tab of your GitHub repo, rather than just hidden in the text logs.

3. Artifact Isolation​

  • If you are building multiple versions (e.g., a Free version and a Pro version of your website), ensure their artifacts are named uniquely. This prevents the "Artifact Overwrite" bug where a developer might accidentally deploy the "Free" version's security configuration to the "Pro" server.

4. Environment Variable Injection​

  • Never bake environment-specific variables (like DB_URL) into the build artifact. The artifact should be Environment Agnostic. Inject the variables only during the Deployment phase.

Caching is like keeping a "Inventory". If you already bought the groceries yesterday, you don't go back to the market today. You just check if anything is expired (Security Scan) and use what you have. This saves "Petrol" (CI Minutes) and "Time" (Developer Wait-time).

8. Cache & Performance Optimization​

TopicShort NotesOfficial Doc****Why Caching is ImportantEvery time a runner starts, it is empty. Downloading 500MB of node_modules every time is a waste of money and time. Caching stores these files in GitHub's storage and "injects" them into the runner. For a website, this can reduce build time from 10 minutes to 2 minutes.Caching OverviewDependency CachingUse actions/cache or built-in caching in setup-node, setup-python, etc. Even if you cache dependencies, your Vulnerability Scanner (Snyk/Trivy) must still run. A cached package might have been safe yesterday but discovered to be a "Zero-Day" risk today.Dependency CacheCache Keys & Restore KeysThe key is usually a hash of your lock file: ${{ hashFiles('package-lock.json') }}. If one character in that file changes, the cache is invalidated. restore-keys allow you to download the "next best" cache if an exact match isn't found, which still saves time.Cache KeysCache InvalidationThis is the "Expiry Date" of your cache. Force a cache clear if a major security patch is released for our environment. Stale caches are the #1 reason for "It works on my machine but fails in CI" bugs.Managing CacheAvoiding Unnecessary JobsUse on: push: paths:. If a developer only changes the docs/ folder, do not trigger the "Deployment" job. This reduces the "Attack Surface" because you aren't running privileged code for non-code changes.ConditionsReducing Checkout SizeUse actions/checkout@v4 with fetch-depth: 1. This is a "Shallow Clone." It only downloads the latest commit, not the 10-year history of the project. It's faster and more secure as it limits the amount of source code metadata on the runner.Checkout StrategySpeed vs ReliabilityNever sacrifice security for speed. If a DAST scan takes 15 minutes, let it run. However, you can move it to a "Post-Deploy" phase or run it in parallel with other tests to minimize the "Blocking" time.GHA Best PracticesCaching vs Security RiskNever cache .env files, node_modules that contain local secrets, or compiled binaries that haven't been scanned. Caches are stored in plain text (unencrypted) in GitHub's internal storage. If an attacker gains access to your repo, they can download your cache.Security GuidesCache Scope & IsolationCaches are isolated by branch. A PR from a "Fork" cannot access the main branch cache. This prevents "Cache Poisoning", where a malicious contributor tries to upload a "Hacked" version of a library into your cache to infect your production build.Cache ScopesTuning Security ToolsTools like CodeQL can be slow. Use "Incremental Scanning" and cache the CodeQL database. This ensures that only the changed code is scanned deeply, while the rest of the app is verified against the previous "Safe" state.CodeQL PerformanceFail-Fast StrategySet continue-on-error: false for security steps. Use exit 1 as soon as a critical bug is found. Why wait for the whole 20-minute pipeline to finish if you already know the security scan failed in the first 2 minutes?Status ChecksPipeline ObservabilityUse the "Usage" tab in GitHub Actions to see which jobs are taking the most time and money. look for "Spikes" in time if a scan suddenly takes 2x longer, it might mean the code has become too complex or a tool is hanging.Monitoring

9. Secrets, Variables & Environment Protection​

**TopicShort NotesOfficial Doc****Repository Variables (vars)**Use for non-sensitive data like API_URL or APP_COLOR. Accessible via ${{ vars.NAME }}. Unlike secrets, these are visible in plain text in settings and logs, so never put passwords here.Store Info in VariablesRepository SecretsEncrypted data like AWS_ACCESS_KEY. GitHub automatically masks these in logs with ***. Master Note: Even if you try to print them, GitHub's "Secret Redactor" will catch and hide them.Using SecretsEnvironment SecretsSecrets tied to a specific environment (e.g., Prod_DB_Password). This prevents a developer from accidentally using the Production database while working on a "Dev" branch.Environment SecretsOrganization SecretsShared across multiple repositories. Great for company-wide secrets like a "Corporate NPM Token." Use the "Selected Repositories" policy to limit which repos can access them.Org SecretsDeployment Protection RulesGates that must be passed before a job runs in an environment. This includes Required Reviewers (someone must click "Approve") and Wait Timers (cooldown period).Protection RulesCustom Deployment RulesCan use third-party tools (like Honeycomb or Datadog) to "Gate" a deployment. If your server's error rate is too high, the rule automatically fails the deployment.Custom Rules**OpenID Connect (OIDC)**The modern way to connect to AWS/Azure/GCP. Instead of storing a long-lived "Secret Key," GitHub uses a short-lived token to talk to your Cloud provider. No keys to steal = Maximum security.About OIDC**Secret Masking add-mask**If you generate a sensitive value dynamically (like a temporary token), use the command echo "::add-mask::$VALUE". This tells GitHub to treat that specific value as a secret and hide it from all logs.Masking DataGITHUB_TOKEN PermissionsEvery workflow has a temporary GITHUB_TOKEN. By default, it might have too much power. Always set permissions: contents: read to follow the Least Privilege Principle.Token PermissionsPreventing Script InjectionNever use untrusted input (like a PR title) directly in a run command. A hacker can name their PR "; rm -rf / #" to destroy your runner. Always map inputs to Environment Variables first.Script InjectionArtifact AttestationsCreate a tamper-proof record (provenance) of how your website was built. This allows you to verify that the code on your server is exactly what was built in GitHub, preventing "Supply Chain" attacks.Artifact AttestationsBranch/Tag RestrictionsLimit which branches can deploy to "Production." Usually, you only want the main branch or specific v* tags to have permission to use production secrets.Branch RestrictionsSecret Rotation PolicySecrets shouldn't live forever. setup includes a Scheduled Workflow that automatically rotates cloud API keys every 30-90 days using the GitHub API.Rotating Secrets

10. Security & DevSecOps​

TopicShort NotesOfficial Doc****CI/CD Threat ModelUnderstand the 3 main threats: Secret Exfiltration (stealing keys), Supply Chain Attacks (poisoning dependencies), Build Injection (hacking the build to add a backdoor). DevSecOps treat the runner as a "Hostile Environment."Hardening ActionsGHA Permission ModelThe GITHUB_TOKEN is your "Passport." By default, it can do almost anything. A Master setup overrides this globally. If you don't define permissions, you are leaving your "Passport" on the table for any hacker to pick up.Workflow Permissions**Least Privilege (PoLP)**Start with permissions: {} (Zero access). Then, add only what you need. For example, a security-scan job only needs security-events: write to upload results. It doesn't need to "Write" to your source code.Least PrivilegeJob vs Workflow PermissionsDefine broad read-only at the workflow level but define specific write permissions inside the Job block. This ensures that the "Build" job can't accidentally do what the "Deploy" job is supposed to do.Workflow Syntax**OIDC (Keyless Auth)**The "Gold Standard": Instead of saving AWS Access Keys as secrets (which never expire), use OIDC. GitHub "introduces" itself to AWS using a temporary token. This token dies after the job ends. If a hacker steals it, it's useless after 10 minutes.About OIDCSecret ScanningGitHub built-in scans. Enable "Push Protection." If a developer tries to push code containing a Google Map API key or AWS secret, GitHub will REJECT the push immediately. Prevention is better than a cure.Secret Scanning**Dependency Scanning (SCA)**Use Dependabot. It doesn't just scan; it opens a Pull Request automatically to fix the vulnerability. In DevSecOps, we call this "Auto-Remediation."Dependabot Alerts**SAST (Code Scanning)**Use CodeQL. It "compiles" your code into a database and runs queries to find logical flaws like "SQL Injection" or "Buffer Overflows." It's like having a senior security engineer review every single line of code in seconds.About CodeQLSecurity Anti-Patterns1. Using pull_request_target with untrusted code. 2. Not pinning actions to a SHA. 3. Using sudo in shell scripts. 4. Printing secrets in debug logs. identifies and blocks these during the PR review.Security Hardening**Action Pinning (SHA)**Never use actions/checkout@v4. Use the full 40-character commit hash. Tags like v4 can be moved by a hacker. A Commit Hash (SHA) is immutable. This is the #1 way to prevent Supply Chain Attacks.Action Versioning**Dynamic Analysis (DAST)**Unlike SAST, DAST (using tools like OWASP ZAP) scans the website while it's running in Staging. It finds "Runtime" issues that static code analysis might miss, like broken SSL or insecure headers.Security in GHAGovernance & AuditFor large teams, use Organization-level Policies. Mandate that every single repository in your company MUST run a security scan before the "Merge" button becomes active.Security Policies

11. Supply-Chain Security​

**TopicShort NotesOfficial Doc****What is Supply-Chain Security?**It is the practice of securing everything that "touches" your code before it reaches the user. This includes 3rd-party Actions, NPM/Pip libraries, and even the Runner images. In DevSecOps, we assume that any external dependency is "Guilty until proven Innocent."Hardening GHA**Pinning Action Versions (SHA)**Never use @v4 or @master. Use the full 40-character Commit SHA (e.g., actions/checkout@a1b2c3d...). Why? Because a hacker can hijack a "Tag" and push malicious code to it, but a "Commit SHA" is immutable it can never be changed.Pinning ActionsVerifying 3rd-Party ActionsTreat the GitHub Marketplace like a public street. Before using an action, check:

  1. Is the creator "Verified" (Blue checkmark)?
  2. How many stars does it have?
  3. Does it ask for high permissions? A DevSecOps pro reads the source code of an action before trusting it with the company's secrets.Marketplace Security**SBOM (Software Bill of Materials)**It lists every single library used in your build. you don't have to search your code; you just check your SBOM to see if you are affected.About SBOMsBuild Provenance & AttestationProvenance is the "Certificate of Origin." It is a digitally signed document that proves: "This build.zip was created on GitHub Runner #123, using the main branch, and passed all security scans." It prevents anyone from replacing your website files with a fake version.Build ProvenanceDependency ReviewThis is a specialized GHA feature. When a developer adds a new NPM package in a PR, GitHub automatically compares it against a database of "Bad Packages." It blocks the PR if the new dependency is known to be malicious or has a risky license.Dependency ReviewPrivate RegistriesFor security, don't pull packages directly from the public internet (NPM/PyPI). Use a Private Registry (like GitHub Packages or JFrog) where packages are scanned and "Approved" by the security team before developers can use them.GitHub Packages

12. Advanced Security Scenarios​

TopicShort NotesOfficial Doc****Secure Handling of LogsGitHub masks secrets, but it’s not 100% foolproof. If a tool prints a secret in Base64 or Hex format, GitHub won't catch it.** **Use set +x in shell scripts to prevent printing commands and always use the ::add-mask:: command for dynamic values generated during the build.Hardening GHA LogsForked PR Security RisksPublic forks are untrusted. By default, GHA blocks secrets for PRs from forks. This prevents an attacker from creating a PR that simply says echo $AWS_SECRET. Never manually enable "Send secrets to forks" unless you have a very specific, isolated setup.PR SecuritySafe Patterns for OSSFor Open Source Websites, use a "Label-Triggered" workflow. The CI only runs after a maintainer reviews the code and adds a "safe to test" label. This prevents "Crypto-mining" attacks where hackers use your CI minutes to mine Bitcoin.OSS SecurityScript Injection Preventionrun: echo "Hello ${{ github.event.pull_request.title }}". If the PR title is "; rm -rf /", your runner is dead. Safe Pattern: Always map the dynamic input to an Environment Variable first, then use the variable in the script.Injection RisksBypassing Security GatesSometimes people use [skip ci] in commit messages to bypass security. Configure Branch Protection Rules that require specific status checks (like the Scan job) to pass, regardless of what the commit message says.Protection Rules

13. Advanced Workflow Design​

TopicDetailed Notes (Pro-Level Perspective)Official DocumentationReusable Workflows (workflow_call)**The Corporate Standard: Allows you to define a "Master Workflow" in a central repo. Other repos "call" it. Use this to mandate that "No project can deploy without calling the 'Company-Security-Scan' workflow." It prevents developers from "forgetting" security steps.Reusable WorkflowsComposite ActionsGroups multiple steps (e.g., Setup Node + NPM Install + Run Linter) into a single Action. Great for clean code. Note: Unlike reusable workflows, these run within the caller's job context and cannot have their own "Jobs" or "Secrets" management they share everything with the parent.Composite ActionsDocker-Based ActionsRuns your action inside a specific Docker container. This is the most secure way to run "Heavy" security tools (like OWASP ZAP) because the tool is isolated in its own container. Always scan the base image of your Docker Action for vulnerabilities.Docker ActionsCross-Repo WorkflowsUsing the repository_dispatch event to trigger a workflow in Repo B from Repo A. Security Risk: This requires a Personal Access Token (PAT). use Fine-grained PATs with the absolute minimum access required to prevent a "Chain Reaction" if one repo is hacked.Workflow DispatchCentral CI RepositoriesA dedicated repository (e.g., .github repo in an Org) that stores all standard workflows. This is "Governance as Code." It allows the Security Team to update the "Global Security Gate" without asking 50 developers to change their code.Organization WorkflowsMonorepo PipelinesManaging multiple websites/services in one repo. Use paths filters to avoid "Pipeline Overload." Ensure that a vulnerability in the frontend doesn't allow a developer to bypass security checks for the backend just because they are in the same repo.Monorepo StrategyDynamic MatricesInstead of hardcoding [node-18, node-20], use a job that detects which versions are needed and outputs a JSON string to the next job. This makes your CI/CD "Intelligent" and saves thousands of CI minutes.Dynamic Matrix**Workflow VersioningThe Pro Move: Reference reusable workflows using a specific version or tag: my-org/shared/.github/workflows/ci.yml@v1.2.0. This ensures that a breaking change in the "Master Workflow" doesn't take down every website in the company.Versioning

14. Enterprise & Platform Engineering​

TopicShort NotesOfficial Doc****CI/CD as a PlatformShift from "Scripts" to "Service." The Platform team provides a set of tools (GHA, Runners, Security Scanners) that any team can use. Enable Required Workflows at the Organization level so teams cannot delete security steps even if they try.Enterprise GHAGolden PipelinesThese are the "Certified" templates. If a team uses the Golden Pipeline, they are automatically compliant with company security policies. This reduces "Shadow IT" where teams create their own insecure ways to deploy.Reusable Workflows**Internal Developer Platforms (IDP)**A layer above GitHub that simplifies things. Instead of writing YAML, a developer might fill a form: "I want a React Website," and the IDP automatically generates the Repo, the GHA workflows, and the Cloud infrastructure with OIDC already set up.Platform EngineeringSelf-Service PipelinesEmpowerment without risk. Using workflow_dispatch with Inputs, developers can deploy to "Staging" manually. However, the DevSecOps team restricts the "Production" trigger to only specific service accounts or senior leads.Workflow DispatchGovernance & PolicyUse GitHub Repository Rulesets. You can block any push that tries to delete the .github/workflows folder or modify the "Deployment Protection" settings. This is "Guardrail" security.Repo RulesetsCODEOWNERS for WorkflowsCreate a CODEOWNERS file in the .github/ directory. Direct it so that any change to a YAML file requires approval from the @Company-DevSecOps team. This stops "Pipeline Hijacking" by rogue developers.CODEOWNERS**Separation of Duties (SoD)**The Compliance Rule: The person who writes the code cannot be the same person who approves the deployment. GHA Environments enforce this by requiring a "Third-party" reviewer from the QA or Security team.EnvironmentsMulti-Org CI/CD DesignEnterprises often have "Dev-Org" and "Prod-Org." Workflows in the Dev-Org build the artifact, and a "Cross-Org" action promotes it to the Prod-Org. This provides a "Hard Firewall" between development and live customer data.Enterprise Cloud

14. Observability, Reliability & Cost​

TopicShort NotesOfficial Doc****Pipeline LoggingLogs are the primary evidence during a "Post-Mortem." Use "Job Summaries" ($GITHUB_STEP_SUMMARY) to create a high-level security dashboard inside the GHA UI. This allows managers to see security results without digging through thousands of lines of raw text logs.Logging & DebuggingMetrics & Audit LogsThese provide the "Who, What, When." From a DevSecOps view, audit logs are essential for proving that a deployment was authorized. If a secret is leaked, audit logs tell you which runner was used and who had access to that specific workflow run.Audit Log EventsSLOs & SLIs for CI/CD****SLI (Indicator): Time to finish a security scan. SLO (Objective): 95% of security scans must finish under 10 minutes. If your pipeline is slow, developers will find "hacks" to bypass it. Reliability of the pipeline is a prerequisite for Security.Monitoring ActionsFlaky Pipeline HandlingA flaky pipeline is one that fails 1 out of 10 times for no reason. Security Risk: Developers get "Alert Fatigue" and start ignoring failures, which might hide a real security vulnerability. Use the continue-on-error: false and investigates every single "Random" failure.Troubleshooting**Cost Optimization (FinOps)**GHA isn't free. Strategy: Use timeout-minutes on every job. A "stuck" security scanner shouldn't run for 6 hours. Use Matrix strategically don't test on 20 OS versions if 2 are enough for your website's risk profile.Billing ManagementBuild Minute BudgetingUse the GitHub API to export usage data to a dashboard (like Grafana). This helps identify "Expensive Repos." In DevSecOps, we justify the cost of security scans by comparing it to the potential cost of a data breach.GHA BillingFinOps + DevSecOpsThis is the art of "Secure Efficiency." For example, using "Shallow Clones" reduces data transfer costs. Running scans in parallel reduces the "Time-to-Feedback" without increasing the total "Compute Minutes."Usage LimitsBusiness ImpactA 30-minute pipeline means a developer can only deploy 16 times a day. A 5-minute pipeline allows 96 deploys. DevSecOps ensures that speed doesn't lead to "Sloppy Security."Actions Performance

Incidents & Failure Handling (Master Table)​

TopicShort NotesOfficial Doc****Error Handling PatternsUse continue-on-error: true only for non-critical steps (like a "Notice" level linter). For security scans, always use false. This ensures the pipeline acts as a Hard Gate. If the scan fails, the deployment is physically impossible.Conditions & FailureRetry LogicUse the nick-fields/retry action for flaky network calls. Never retry a security scan that failed due to a "Vulnerability Found" error. Retries are for Infrastructure issues, not Security issues.Status Checks**Cleanup using always()**If your job creates a temporary folder or a Docker container with secrets, use a cleanup step with if: always(). This ensures the sensitive data is deleted even if the previous step crashed.Expressions & always()NotificationsIntegrate with Slack/Discord. Send different alerts for different failures. A "Build Failure" goes to the Dev channel; a "Security Scan Failure" goes to the Security/SOC channel with high priority.Workflow CommandsIncident Mode PipelinesWhen a website is down, use a simplified "Recovery" workflow. It bypasses heavy feature tests but keeps mandatory security scans. This allows a Hotfix to go live in 2 minutes instead of 20, safely.Actions IntroFreeze DeploymentsUse Environment Protection Rules to "Lock" the production environment during a holiday or a major incident. This prevents anyone from pushing code that might make a bad situation worse.Deployment GatingEmergency HotfixesUse workflow_dispatch with a hotfix branch. Even in an emergency, ensures that OIDC and Code Scanning still run. Speed must not lead to a secondary data breach.Events GuidePost-Incident LearningUse GitHub's Workflow Run History to perform a "Post-Mortem." Did the security gate fail to catch the bug? Was the log verbosity too low? Feed these lessons back into the "Golden Pipeline".Monitoring & Debugging

Testing & Debugging Workflows (Master Table)​

**TopicShort NotesOfficial Doc****Debug Logs (Step Debugging)**Enable by setting ACTIONS_STEP_DEBUG: true in Secrets. It shows the raw input/output of every action. These logs are very "noisy" and can occasionally bypass masking if a tool prints secrets in an unusual format. Turn off debug logs as soon as the problem is fixed.Enabling DebuggingCommon Workflow Errors1. Context Errors: Trying to access ${{ secrets.X }} in a job that doesn't have permissions. 2. Shell Errors: Using bash commands on a Windows runner. 3. Indentation: YAML is space-sensitive. In DevSecOps, a "wrong space" in a permissions block can actually grant more access than intended.Troubleshooting Guide**YAML Validation (Linters)**Use the GitHub Actions extension in VS Code. It highlights errors in real-time. In an Enterprise setup, use a "Pre-commit hook" that runs a YAML linter (like yamllint) to ensure no "broken" automation ever reaches the server.Workflow SyntaxLocal Testing with actact is a tool that runs GHA workflows inside Docker containers on your PC. It’s a Life-saver. test secret-handling logic locally using a .secrets file without ever uploading sensitive keys to GitHub during the "Trial and Error" phase.act GitHub RepoDry Runs & ValidationUse the workflow_dispatch with a "dry-run" input.