<?xml version="1.0" encoding="UTF-8"?>
<rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/"
    xmlns:atom="http://www.w3.org/2005/Atom" xmlns:media="http://search.yahoo.com/mrss/" version="2.0">
    <channel>
        
        <title>
            <![CDATA[ GitHub - freeCodeCamp.org ]]>
        </title>
        <description>
            <![CDATA[ Browse thousands of programming tutorials written by experts. Learn Web Development, Data Science, DevOps, Security, and get developer career advice. ]]>
        </description>
        <link>https://www.freecodecamp.org/news/</link>
        <image>
            <url>https://cdn.freecodecamp.org/universal/favicons/favicon.png</url>
            <title>
                <![CDATA[ GitHub - freeCodeCamp.org ]]>
            </title>
            <link>https://www.freecodecamp.org/news/</link>
        </image>
        <generator>Eleventy</generator>
        <lastBuildDate>Mon, 16 Nov 2026 00:30:54 +0000</lastBuildDate>
        <atom:link href="https://www.freecodecamp.org/news/tag/github/rss.xml" rel="self" type="application/rss+xml" />
        <ttl>60</ttl>
        
            <item>
                <title>
                    <![CDATA[ How to Speed Up CI in the Age of AI-Written Code ]]>
                </title>
                <description>
                    <![CDATA[ Coding agents now write code faster than most CI pipelines can check it. In April 2026, GitHub COO Kyle Daigle said that his platform was handling 275 million commits a week, on pace for 14 billion in ]]>
                </description>
                <link>https://www.freecodecamp.org/news/speed-up-ci-in-the-age-of-ai-written-code/</link>
                <guid isPermaLink="false">6af7069e2028f50f83240511</guid>
                
                    <category>
                        <![CDATA[ GitHub ]]>
                    </category>
                
                    <category>
                        <![CDATA[ ci ]]>
                    </category>
                
                    <category>
                        <![CDATA[ ci-cd ]]>
                    </category>
                
                    <category>
                        <![CDATA[ AI ]]>
                    </category>
                
                    <category>
                        <![CDATA[ agentic AI ]]>
                    </category>
                
                <dc:creator>
                    <![CDATA[ Manish Shivanandhan ]]>
                </dc:creator>
                <pubDate>Fri, 13 Nov 2026 12:46:22 +0000</pubDate>
                <media:content url="https://cdn.hashnode.com/uploads/covers/5fc16e412cae9c5b190b6cdd/d1609f3b-9a5c-402f-b04d-30349dd2e10e.png" medium="image" />
                <content:encoded>
                    <![CDATA[ <p>Coding agents now write code faster than most <a href="https://www.freecodecamp.org/news/learn-continuous-integration-delivery-and-deployment/">CI pipelines</a> can check it. In April 2026, <a href="https://x.com/kdaigle/status/2040164759836778878">GitHub COO Kyle Daigle said</a> that his platform was handling 275 million commits a week, on pace for 14 billion in the year, up from about 1 billion in 2025. In the same post, he put GitHub Actions at 2.1 billion minutes in a single week, up from 500 million a week in 2023.</p>
<p>That second figure shows where all those commits end up: in CI. A 15-minute pipeline is tolerable if a dev pushes a few times a day. When an agent opens ten PRs in an afternoon, that pipeline turns into a queue. You wait for results, agents wait to retry, and the time saved writing code is lost checking it.</p>
<p>Most of that delay comes from a few causes, and each has a known fix. You can speed up CI in five ways:</p>
<ol>
<li>measure where the time goes</li>
<li>cache what you can reuse</li>
<li>run jobs on faster hardware</li>
<li>split tests across parallel jobs</li>
<li>skip work that doesn't need to run.</li>
</ol>
<p>In this article, we'll walk through each fix in order. You’ll learn how to find the slowest steps in your GitHub Actions workflows, cache dependencies and Docker layers with stable keys, and move heavy jobs to faster runners. You’ll also see how to shard tests across a matrix of parallel jobs, and how to skip unneeded work with path filters, affected-only tests, and concurrency groups.</p>
<h3 id="heading-what-well-cover">What We'll Cover:</h3>
<ul>
<li><a href="#heading-measure-first-then-optimize">Measure First, Then Optimize</a></li>
<li><a href="#heading-cache-dependencies-and-build-layers">Cache Dependencies and Build Layers</a></li>
<li><a href="#heading-run-on-faster-hardware">Run on Faster Hardware</a></li>
<li><a href="#heading-parallelize-and-shard-your-tests">Parallelize and Shard Your Tests</a></li>
<li><a href="#heading-do-less-work-on-every-run">Do Less Work on Every Run</a></li>
<li><a href="#heading-putting-it-together">Putting It Together</a></li>
</ul>
<h2 id="heading-measure-first-then-optimize">Measure First, Then Optimize</h2>
<p>Most teams try to guess which step is slowing things down, and they're often wrong. A job that feels like a test problem may be 90 seconds of installs and 30 seconds of tests.</p>
<p>Start with data you already have. GitHub shows <a href="https://docs.github.com/en/actions/how-tos/monitor-workflows/view-job-execution-time">job execution time</a> for every run, with a timing for each step. Open the last ten runs of your slowest workflow and note the three longest steps. Use the median, not the worst case, since one slow run can be a network blip.</p>
<p>Also separate waiting from working. Queue time, setup time, and run time need different fixes. If jobs sit in a queue for a minute, no test tuning will help.</p>
<h2 id="heading-cache-dependencies-and-build-layers">Cache Dependencies and Build Layers</h2>
<p>The fastest work is work you never repeat. Every run starts on a fresh machine, so without a cache you download the same packages again and again.</p>
<p>The <a href="https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching">dependency caching reference</a> explains how <code>actions/cache</code> works. You give it a path and a key. If the key matches a saved cache, the files are restored. If not, the step runs, and the files are saved when the job ends.</p>
<p>Everything depends on that key. The usual pattern hashes your lockfile, so the key changes only when your dependencies change.</p>
<pre><code class="language-yaml">- uses: actions/cache@v6
  with:
    path: ~/.npm
    # Key changes only when the lockfile changes
    key: npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      npm-${{ runner.os }}-
</code></pre>
<p>The <code>restore-keys</code> line is the part that tends to get skipped. When the exact key misses, it restores the closest older cache. You still install a few new packages, but not all of them. Be careful with keys that include a timestamp or a commit SHA. Those never match twice, so you save a new cache on every run and never reuse one.</p>
<p>Docker builds need the same thinking. Docker images are built in layers, and a layer is reused only if everything above it is unchanged. Copy your lockfile and install dependencies first, then copy your source code. That way a code change doesn't rebuild the install layer. To keep layers between runs, point BuildKit at the <a href="https://docs.docker.com/build/cache/backends/gha/">GitHub Actions cache backend</a> with <code>cache-from</code> and <code>cache-to</code> set to <code>type=gha</code>.</p>
<p>One catch is that these caches live in remote storage. Each restore is a network download, which on a big cache can rival the install it replaces.</p>
<h2 id="heading-run-on-faster-hardware">Run on Faster Hardware</h2>
<p>Caching avoids repeating work. This improvement is different. It runs the work itself on faster machines.</p>
<p>Standard GitHub-hosted runners for private repositories have 2 vCPUs and 7 GB of RAM. <a href="https://avrea.com/">Avrea</a> is a drop-in replacement for GitHub Actions runners. You change one line, from <code>runs-on: ubuntu-latest</code> to an Avrea label such as <code>runs-on: avrea-ubuntu-latest</code>, and the rest of your workflow stays the same. By Avrea's own numbers, jobs run about 2x faster on hardware alone, and up to 10x faster with cache hits.</p>
<p>Independent numbers point the same way. RunsOn maintains a <a href="https://runs-on.com/benchmarks/runners/">public runner benchmark</a> that builds three open-source projects on nine runner services with build caches turned off: a Rust test suite, TypeScript typechecks, and a production Docker build of PostHog. In the 4-vCPU x64 category, as of November 2026, Avrea finished all three in about 7 minutes of build time, compared with about 18.5 minutes on GitHub's 4-core runner, not counting runner start-up.</p>
<p>Built-in caching is the other half, and it connects to the section above. Avrea keeps its caches in the same datacenter as its runners, so a restore doesn't cross a slow network. Most of it is pre-configured.</p>
<p>The GitHub Actions cache and package downloads for npm, pip, Go modules, and Cargo work with no workflow changes. Build caches for tools such as Go, Bazel, Gradle, Turborepo, Nx, and sccache are set up on the runner, and some need a small workflow addition. So a team gets cache hits without writing key logic for each tool.</p>
<p>Other providers take other routes. <a href="https://depot.dev/">Depot</a> offers faster GitHub Actions runners and remote Docker builds, and now runs its own CI engine that accepts GitHub Actions workflows. <a href="https://runs-on.com/">RunsOn</a> is self-hosted: it starts EC2 instances inside your own AWS account, so you pay AWS for compute plus a flat yearly license, instead of a per-minute fee to RunsOn. GitHub's own <a href="https://docs.github.com/en/actions/concepts/runners/larger-runners">larger runners</a>, available on Team and Enterprise Cloud plans, add more CPU, RAM, and disk, plus options like static IPs and GPUs, billed by the minute. Check each provider's site for current details, since all of them change often.</p>
<h2 id="heading-parallelize-and-shard-your-tests">Parallelize and Shard Your Tests</h2>
<p>Once each job is fast, make sure jobs don't wait in a line. A long test suite on one runner is the classic bottleneck.</p>
<p>Start with independent jobs. Lint, type checks, unit tests, and build rarely need each other. GitHub runs jobs in parallel unless you add <code>needs</code>, so remove any <code>needs</code> line that's only there for habit.</p>
<p>Next, use a matrix. A <a href="https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/run-job-variations">matrix strategy</a> creates one job per combination of values, and they all run at once. Teams often use it for Node versions, but it's also the simplest way to shard tests.</p>
<pre><code class="language-yaml">strategy:
  fail-fast: false
  matrix:
    shard: [1, 2, 3, 4]
steps:
  # Each job runs one quarter of the suite
  - run: npx jest --shard=${{ matrix.shard }}/4
</code></pre>
<p>Jest's <code>--shard</code> flag splits the suite across jobs by test file. Four shards can turn a twelve-minute suite into about three, plus setup time, if the files take similar time. If a few files are much heavier, one shard will run long, so split those files up. Setting <code>fail-fast: false</code> lets every shard finish, so you see all failures at once.</p>
<p>Playwright works the same way. Run <a href="https://playwright.dev/docs/test-sharding"><code>npx playwright test --shard=1/4</code></a> in each matrix job, then merge the reports at the end.</p>
<p>Sharding has a limit. Each shard pays its own setup cost, so past a point more shards add cost without saving time. Inside a single job, tools like <a href="https://pytest-xdist.readthedocs.io/en/stable/">pytest-xdist</a> spread tests across the CPUs on the machine.</p>
<h2 id="heading-do-less-work-on-every-run">Do Less Work on Every Run</h2>
<p>The last one is the cheapest: don't run what you don't need to run.</p>
<p>Path filters are the easiest start. In the <a href="https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax">workflow syntax</a>, the <code>paths</code> and <code>paths-ignore</code> keys let a workflow run only when certain files change. A change to the docs folder shouldn't trigger a full backend build.</p>
<p>One warning: if a required status check never runs because of a path filter, the pull request stays stuck on a pending check. For required checks, let the workflow run and skip the job with an <code>if:</code> condition instead, since GitHub counts a skipped job as passed.</p>
<p>In a monorepo, go further and run only affected tests. Tools such as Nx, Turborepo, and Bazel work out which packages a change touches and skip the rest. In Nx that's <code>nx affected -t test</code>, and in Turborepo it's <code>turbo run test --affected</code>. Both compare your branch against <code>main</code>, so check out enough Git history for that comparison, since <code>actions/checkout</code> fetches a single commit by default.</p>
<p>Most commits touch a small part of a large codebase, so the savings add up. This matters more when agents open many small pull requests, each touching a package or two.</p>
<p>Finally, stop paying for runs that no one needs. When you push twice in a row, the first run is already out of date. A <a href="https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/control-workflow-concurrency">concurrency group</a> cancels it.</p>
<pre><code class="language-yaml">concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  # Cancel the older run when a new push arrives
  cancel-in-progress: true
</code></pre>
<p>This matters more as AI tools push more commits. Agents may update a branch many times an hour, and each push starts a full run. Don't use it on deploy workflows, though. Cancelling a deploy halfway can leave a bad state, so queue those instead.</p>
<h2 id="heading-putting-it-together">Putting It Together</h2>
<p>Measure first, because that shows which of the other four fixes is worth your time. Cache with stable keys and order your Dockerfile so slow layers stay put. Move heavy jobs to faster runners, and compare providers on your own workflow. Shard tests until setup time dominates. Then cut needless work with path filters, affected-only tests, and cancelled stale runs.</p>
<p>Make one change at a time and re-check your timings after each. Saving two minutes on a job that runs fifty times a day beats a clever fix on a job that runs once.</p>
<p>Hope you enjoyed this article. You can <a href="https://linkedin.com/in/manishmshiva"><u>connect with me on LinkedIn</u></a>.</p>
 ]]>
                </content:encoded>
            </item>
        
            <item>
                <title>
                    <![CDATA[ How to Build Ephemeral PR Preview Environments on GKE with GitHub Actions, Ingress, and Automatic TLS ]]>
                </title>
                <description>
                    <![CDATA[ Every team that ships software eventually builds a staging environment. And every team that builds a staging environment eventually discovers the same problem. Staging is shared. One environment, many ]]>
                </description>
                <link>https://www.freecodecamp.org/news/build-ephemeral-pr-preview-environments-on-gke-with-github-actions-ingress-automatic-tls/</link>
                <guid isPermaLink="false">6ad0d6b41b1aaeb205d2d198</guid>
                
                    <category>
                        <![CDATA[ Kubernetes ]]>
                    </category>
                
                    <category>
                        <![CDATA[ gke ]]>
                    </category>
                
                    <category>
                        <![CDATA[ Terraform ]]>
                    </category>
                
                    <category>
                        <![CDATA[ ephemeral ]]>
                    </category>
                
                    <category>
                        <![CDATA[ GitHub ]]>
                    </category>
                
                    <category>
                        <![CDATA[ ci-cd ]]>
                    </category>
                
                <dc:creator>
                    <![CDATA[ Amina Lawal ]]>
                </dc:creator>
                <pubDate>Thu, 15 Oct 2026 13:35:48 +0000</pubDate>
                <media:content url="https://cdn.hashnode.com/uploads/covers/5e1e335a7a1d3fcc59028c64/8d8182a7-81dd-4bb8-bd62-f9e3c4175532.png" medium="image" />
                <content:encoded>
                    <![CDATA[ <p>Every team that ships software eventually builds a staging environment. And every team that builds a staging environment eventually discovers the same problem.</p>
<p>Staging is shared. One environment, many pull requests. Someone deploys a half-finished feature to test it. Someone else deploys on top of that. A third person runs a database migration. By Thursday afternoon, nobody can tell which version of which branch is actually running, and the sentence "it works on staging" has stopped carrying any information at all.</p>
<p>The workarounds are familiar: a Slack channel where people claim staging like a meeting room, a rotating deploy schedule, or a second staging environment, then a third, each one drifting further from production configuration than the last.</p>
<p>There's a better pattern, and platform teams at companies like Vercel, Netlify, and Shopify have made it standard: <strong>give every pull request its own environment</strong>.</p>
<p>Open a PR, and a fresh, isolated copy of your application deploys automatically. Push another commit, and it updates. Merge or close the PR, and the whole thing deletes itself. No queue, no claiming, no cleanup, and no drift.</p>
<p>That's what we're building in this tutorial. Here's what it looks like from the reviewer's side. A bot comment appearing on the pull request with a live, working URL</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/366bb671-d2cb-41e5-859b-aa2242c9dd77.png" alt="A GitHub pull request thread showing an automated bot comment titled &quot;Preview environment is ready&quot;, containing a live HTTPS URL, the commit SHA, and the namespace name, with all checks passing below it." style="display: block;" width="2366" height="1434" loading="lazy">

<h2 id="heading-what-youll-build">What You'll Build</h2>
<p>By the end of this handbook, you'll have a working system where:</p>
<ul>
<li><p>Opening a pull request triggers a GitHub Actions workflow that builds a container image tagged specifically for that PR</p>
</li>
<li><p>The image is pushed to Google Artifact Registry</p>
</li>
<li><p>A dedicated Kubernetes namespace (<code>pr-42</code>, <code>pr-43</code>, and so on) is created inside a GKE cluster, with resource quotas applied before anything deploys</p>
</li>
<li><p>The application deploys into that namespace, completely isolated from every other PR's environment</p>
</li>
<li><p>A shared Ingress controller routes <code>pr-42.preview.yourdomain.com</code> to that namespace, with a valid TLS certificate issued automatically</p>
</li>
<li><p>A bot comments the live URL on the pull request, updating the same comment on every push</p>
</li>
<li><p>Pushing new commits redeploys the environment with the updated code</p>
</li>
<li><p>Closing or merging the PR deletes the namespace and everything inside it</p>
</li>
<li><p>A scheduled job catches any environment the teardown missed</p>
</li>
</ul>
<p>You'll also build the underlying infrastructure with Terraform, with three key design decisions, each with its own section.</p>
<ol>
<li><p><strong>No service account keys:</strong> GitHub Actions authenticates to Google Cloud through Workload Identity Federation. Short-lived OIDC tokens verified against a repository claim. Service account JSON keys sitting in GitHub secrets are one of the most common security problems in CI/CD pipelines today, and you don't need one.</p>
</li>
<li><p><strong>One load balancer, not one per PR:</strong> A single shared Ingress controller routes every environment by hostname, and one wildcard DNS record covers every hostname that will ever exist. The naïve version provisions a cloud load balancer per environment, which gets expensive quickly.</p>
</li>
<li><p><strong>Cleanup that assumes failure:</strong> Teardown runs when a PR closes. But a scheduled reaper also deletes namespaces whose PR is gone or that have outlived a maximum age, because even 95% effective automated cleanup still leaks, and leaks show up on the bill.</p>
</li>
</ol>
<p>Here's the architecture we're working toward:</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/1a414785-4e82-4e8f-ba58-1e02a093677c.png" alt="Architecture diagram of the complete system. GitHub Actions builds and deploys to a GKE cluster through Workload Identity Federation and Artifact Registry, while browsers reach per-pull-request namespaces through wildcard DNS, a shared Google Cloud load balancer, and an NGINX Ingress controller with cert-manager handling TLS." style="display: block;" width="2136" height="1424" loading="lazy">

<p>The diagram traces two separate paths through the same system.</p>
<p>The solid blue path is automation. A pull request triggers GitHub Actions, which authenticates to Google Cloud through Workload Identity Federation, pushes a PR-tagged image to Artifact Registry, and deploys into a dedicated namespace inside the GKE cluster.</p>
<p>Each namespace (<code>pr-42</code>, <code>pr-43</code>, and so on) holds its own Deployment, Service, and Pod, completely isolated from every other one.</p>
<p>Two more automated pieces sit alongside it: a bot that posts and updates the preview URL on the pull request, and a scheduled reaper that finds and deletes orphaned namespaces.</p>
<p>The dashed green path is public traffic. A browser request for a preview URL resolves through a single wildcard DNS record to one Google Cloud load balancer, which hands it to a shared NGINX Ingress controller. That controller reads the request's <code>Host</code> header and routes it to the right namespace. cert-manager runs beside it, requesting certificates from Let's Encrypt so each environment gets its own valid TLS certificate.</p>
<p>The important detail is what <em>doesn't</em> multiply. One load balancer, one DNS record, and one Ingress controller serve every environment, no matter how many pull requests are open.</p>
<h2 id="heading-table-of-contents">Table of Contents</h2>
<ul>
<li><p><a href="#heading-what-youll-build">What You'll Build</a></p>
</li>
<li><p><a href="#heading-prerequisites">Prerequisites</a></p>
</li>
<li><p><a href="#heading-step-1-set-up-the-project-structure">Step 1: Set Up the Project Structure</a></p>
</li>
<li><p><a href="#heading-step-2-write-the-application">Step 2: Write the Application</a></p>
</li>
<li><p><a href="#heading-step-3-write-the-dockerfile">Step 3: Write the Dockerfile</a></p>
</li>
<li><p><a href="#heading-step-4-provision-the-infrastructure-with-terraform">Step 4: Provision the Infrastructure with Terraform</a></p>
</li>
<li><p><a href="#heading-step-5-set-up-keyless-authentication-with-workload-identity-federation">Step 5: Set Up Keyless Authentication with Workload Identity Federation</a></p>
</li>
<li><p><a href="#heading-step-6-apply-the-terraform-configuration">Step 6: Apply the Terraform Configuration</a></p>
</li>
<li><p><a href="#heading-step-7-prove-the-lifecycle-manually">Step 7: Prove the Lifecycle Manually</a></p>
</li>
<li><p><a href="#heading-step-8-write-the-kubernetes-manifests-with-kustomize">Step 8: Write the Kubernetes Manifests with Kustomize</a></p>
</li>
<li><p><a href="#heading-step-9-build-the-spin-up-workflow">Step 9: Build the Spin-Up Workflow</a></p>
</li>
<li><p><a href="#heading-step-10-build-the-teardown-workflow">Step 10: Build the Teardown Workflow</a></p>
</li>
<li><p><a href="#heading-step-11-open-a-pull-request-and-watch-it-work">Step 11: Open a Pull Request and Watch It Work</a></p>
</li>
<li><p><a href="#heading-step-12-reserve-a-static-ip-address">Step 12: Reserve a Static IP Address</a></p>
</li>
<li><p><a href="#heading-step-13-install-the-ingress-controller">Step 13: Install the Ingress Controller</a></p>
</li>
<li><p><a href="#heading-step-14-point-wildcard-dns-at-the-load-balancer">Step 14: Point Wildcard DNS at the Load Balancer</a></p>
</li>
<li><p><a href="#heading-step-15-install-cert-manager-and-create-a-clusterissuer">Step 15: Install cert-manager and Create a ClusterIssuer</a></p>
</li>
<li><p><a href="#heading-step-16-add-an-ingress-to-the-base-manifests">Step 16: Add an Ingress to the Base Manifests</a></p>
</li>
<li><p><a href="#heading-step-17-patch-the-hostname-per-pull-request">Step 17: Patch the Hostname Per Pull Request</a></p>
</li>
<li><p><a href="#heading-step-18-add-guardrails-with-resourcequota-and-limitrange">Step 18: Add Guardrails with ResourceQuota and LimitRange</a></p>
</li>
<li><p><a href="#heading-step-19-update-the-deploy-workflow">Step 19: Update the Deploy Workflow</a></p>
</li>
<li><p><a href="#heading-step-20-comment-the-url-on-the-pull-request">Step 20: Comment the URL on the Pull Request</a></p>
</li>
<li><p><a href="#heading-step-21-build-the-reaper">Step 21: Build the Reaper</a></p>
</li>
<li><p><a href="#heading-step-22-test-the-whole-thing">Step 22: Test the Whole Thing</a></p>
</li>
<li><p><a href="#heading-what-this-costs">What This Costs</a></p>
</li>
<li><p><a href="#heading-cleanup">Cleanup</a></p>
</li>
<li><p><a href="#heading-conclusion">Conclusion</a></p>
</li>
<li><p><a href="#heading-project-file-structure">Project File Structure</a></p>
</li>
</ul>
<h2 id="heading-prerequisites">Prerequisites</h2>
<p>Before you start, make sure you have the following ready:</p>
<ul>
<li><p><strong>A Google Cloud project</strong> with billing enabled. If you don't have one, create it at <a href="https://console.cloud.google.com">console.cloud.google.com</a>. Running this tutorial costs roughly $5–10 depending on how long you leave the cluster up. Don't skip the cleanup section at the end.</p>
</li>
<li><p><code>gcloud</code> <strong>CLI</strong> installed and authenticated. Run <code>gcloud auth login</code> to sign in, and <code>gcloud config set project YOUR_PROJECT_ID</code> to point it at your project.</p>
</li>
<li><p><strong>Terraform</strong> version 1.5 or later. Check with <code>terraform version</code>.</p>
</li>
<li><p><code>kubectl</code> installed. This is the CLI for interacting with Kubernetes clusters.</p>
</li>
<li><p><strong>Docker</strong> installed locally, for testing the build before you hand it to CI.</p>
</li>
<li><p><strong>A GitHub repository</strong> that you own. This needs to be a repository you can push branches to and open pull requests against, since that's the trigger for everything we build.</p>
</li>
<li><p><strong>Basic familiarity with Docker</strong> (images, layers, Dockerfile), <strong>Kubernetes</strong> (pods, deployments, services, namespaces), and <strong>GitHub Actions</strong> (workflows, jobs, steps). You don't need to be an expert, but you should know what these things are.</p>
</li>
<li><p><strong>Helm</strong> version 3, for installing the Ingress controller and cert-manager. Check with <code>helm version</code>.</p>
</li>
<li><p><strong>A domain name you control</strong>, with the ability to add DNS records. It doesn't matter where it's registered. You'll dedicate one subdomain to previews, like <code>preview.yourdomain.com</code>, and every environment lives beneath it.</p>
</li>
</ul>
<p>A note on the domain requirement: this is the part of the project that can't be faked. Let's Encrypt needs to verify that you control the domain before it will issue a certificate, and it verifies this by making a real HTTP request from the public internet. A <code>.local</code> domain, an entry in <code>/etc/hosts</code>, or a domain you don't own won't work.</p>
<p>If you don't have a spare domain, a <code>.dev</code> or <code>.xyz</code> costs a few pounds a year and is worth having for exactly this kind of project.</p>
<p>One more thing worth bringing your attention to early: you'll also need the <code>gke-gcloud-auth-plugin</code>. Recent versions of <code>gcloud</code> prompt you to install it the first time you connect to a GKE cluster. You can install it ahead of time with:</p>
<pre><code class="language-bash">gcloud components install gke-gcloud-auth-plugin
</code></pre>
<h2 id="heading-step-1-set-up-the-project-structure">Step 1: Set Up the Project Structure</h2>
<p>Let's lay out the directories first, so you have a clear mental model of where everything lives.</p>
<pre><code class="language-bash">mkdir -p pr-preview-envs/{app,terraform,k8s/base,.github/workflows}
cd pr-preview-envs
git init
</code></pre>
<p>Here's what each directory holds:</p>
<ul>
<li><p><code>app/</code>: the Go application and its Dockerfile</p>
</li>
<li><p><code>terraform/</code>: infrastructure as code: the GKE cluster, Artifact Registry, and Workload Identity Federation setup</p>
</li>
<li><p><code>k8s/base/</code>: the base Kubernetes manifests that every preview environment is built from</p>
</li>
<li><p><code>.github/workflows/</code>: the two GitHub Actions workflows that create and destroy environments</p>
</li>
</ul>
<p>Connect this to a GitHub repository now, because the Workload Identity Federation setup in Step 5 needs to know your repository's full name (<code>owner/repo</code>):</p>
<pre><code class="language-bash">git remote add origin https://github.com/YOUR_USERNAME/pr-preview-envs.git
</code></pre>
<h2 id="heading-step-2-write-the-application">Step 2: Write the Application</h2>
<p>We need something to deploy. We'll use <strong>Go</strong>, for three reasons that matter to this project specifically.</p>
<p>First, Go compiles to a single statically-linked binary. There's no runtime to install and no interpreter, which means very small container images, and small images mean fast pushes and fast pulls, which matters a lot when you're building an image on <em>every single commit to every open PR</em>.</p>
<p>Second, Go's <code>-ldflags -X</code> mechanism lets us inject values into the binary at build time. We'll use this to bake the PR number and Git commit SHA directly into the application, so the running app can tell us exactly which build it is.</p>
<p>And lastly, build times are fast, and CI minutes aren't free.</p>
<p>Create <code>app/main.go</code>:</p>
<pre><code class="language-go">package main

import (
	"fmt"
	"net/http"
	"os"
)

// These values are empty at compile time and get injected by the
// linker via -ldflags -X during the Docker build. See the Dockerfile.
var (
	prNumber = "local"
	gitSha   = "dev"
)

func handler(w http.ResponseWriter, r *http.Request) {
	// Kubernetes injects these via the Downward API — see deployment.yaml
	namespace := os.Getenv("POD_NAMESPACE")
	podName := os.Getenv("POD_NAME")

	if namespace == "" {
		namespace = "not-in-kubernetes"
	}
	if podName == "" {
		podName, _ = os.Hostname()
	}

	fmt.Fprintf(w, "Preview environment is live\n\n")
	fmt.Fprintf(w, "PR number  : %s\n", prNumber)
	fmt.Fprintf(w, "Git SHA    : %s\n", gitSha)
	fmt.Fprintf(w, "Namespace  : %s\n", namespace)
	fmt.Fprintf(w, "Pod name   : %s\n", podName)
}

func healthz(w http.ResponseWriter, r *http.Request) {
	w.WriteHeader(http.StatusOK)
	fmt.Fprintln(w, "ok")
}

func main() {
	http.HandleFunc("/", handler)
	http.HandleFunc("/healthz", healthz)

	fmt.Println("Server starting on port 8080...")
	if err := http.ListenAndServe(":8080", nil); err != nil {
		fmt.Fprintf(os.Stderr, "server error: %v\n", err)
		os.Exit(1)
	}
}
</code></pre>
<p>Initialize the Go module from inside <code>app/</code>:</p>
<pre><code class="language-bash">cd app
go mod init preview-app
</code></pre>
<p>Let's walk through what this code does and why each piece is here.</p>
<p><code>var prNumber = "local"</code> <strong>and</strong> <code>var gitSha = "dev"</code> are package-level string variables with default values. The defaults are what you'll see if you run the binary locally without going through the Docker build.</p>
<p>During the CI build, the Go linker overwrites them with the real PR number and commit SHA. This is the single most useful debugging feature in the whole project: when you hit a preview environment, the app itself tells you exactly which commit it was built from. There's no guessing.</p>
<p><code>os.Getenv("POD_NAMESPACE")</code> <strong>and</strong> <code>os.Getenv("POD_NAME")</code> read environment variables that Kubernetes injects into the container using something called the <strong>Downward API</strong>. We'll configure that in the deployment manifest in Step 8.</p>
<p>The Downward API lets a pod read metadata about itself (its own name, namespace, and labels) without needing any Kubernetes API credentials. It's the cleanest way for an app to know where it's running.</p>
<p><strong>The</strong> <code>handler</code> <strong>function</strong> is registered on the root path <code>/</code>. It writes the PR number, commit SHA, namespace, and pod name to the response. It's four pieces of information that together answer "what exactly am I looking at right now?"</p>
<p><strong>The</strong> <code>healthz</code> <strong>function</strong> is registered on <code>/healthz</code>, and returns HTTP 200 with the text <code>ok</code>. Kubernetes uses this endpoint for liveness and readiness probes, which we'll wire up in the deployment manifest.</p>
<p><code>http.ListenAndServe(":8080", nil)</code> starts the server on port 8080. If it fails to start, it prints the error and exits with a non-zero code, so Kubernetes knows the container is broken and can restart it.</p>
<p>Test it locally before moving on:</p>
<pre><code class="language-bash">go run main.go
</code></pre>
<p>In a second terminal:</p>
<pre><code class="language-bash">curl http://localhost:8080
</code></pre>
<p>You should see <code>PR number : local</code> and <code>Git SHA : dev</code>, since you're running outside the Docker build. That's the expected local behaviour.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/1ee23b56-dcd8-48f1-a0c8-5c1e3a908d2c.png" alt="Terminal output from curl showing the application reporting PR number &quot;local&quot; and Git SHA &quot;dev&quot; when run outside the Docker build" style="display: block;" width="2744" height="1256" loading="lazy">

<h2 id="heading-step-3-write-the-dockerfile">Step 3: Write the Dockerfile</h2>
<p>Create <code>app/Dockerfile</code>:</p>
<pre><code class="language-dockerfile"># -----------------------------------------------------------
# Stage 1: Build
# -----------------------------------------------------------
FROM golang:1.27-alpine AS builder
#Ensure the version matches what is in your go.mod file

# These are injected by the CI pipeline at build time
ARG PR_NUMBER=local
ARG GIT_SHA=dev

WORKDIR /app

# Copy go.mod first so Docker can cache the dependency layer
COPY go.mod .
RUN go mod download

COPY main.go .

# -w -s strips debug symbols (~30% smaller binary)
# -X overwrites package-level string variables at link time
RUN CGO_ENABLED=0 go build \
    -ldflags="-w -s -X main.prNumber=${PR_NUMBER} -X main.gitSha=${GIT_SHA}" \
    -o server main.go

# -----------------------------------------------------------
# Stage 2: Runtime
# -----------------------------------------------------------
FROM alpine:latest

RUN addgroup -S appgroup &amp;&amp; adduser -S appuser -G appgroup
USER appuser

WORKDIR /app
COPY --from=builder /app/server .

EXPOSE 8080
CMD ["./server"]
</code></pre>
<p>There are a few things happening here worth understanding properly.</p>
<h3 id="heading-1-the-ldflags-x-injection">1. The <code>-ldflags -X</code> Injection</h3>
<pre><code class="language-plaintext">-X main.prNumber=${PR_NUMBER}
</code></pre>
<p>The <code>-X</code> linker flag sets the value of a package-level string variable at link time. The syntax is <code>-X importpath.name=value</code>. Since our variables live in <code>package main</code>, the import path is just <code>main</code>.</p>
<p>This only works on <code>string</code> variables that are already declared in the source. You can't create new variables this way, and you can't inject into an <code>int</code> or a <code>bool</code>. That's why <code>prNumber</code> is a string in <code>main.go</code> even though it holds a number.</p>
<p>Why do this instead of just passing an environment variable through the deployment manifest? Because build metadata belongs to the <em>image</em>, not the <em>deployment</em>. If you pass it as an env var, someone can deploy image <code>abc123</code> with an env var claiming it's commit <code>def456</code>, and the app will happily lie to you. Baking it into the binary means the image can only ever report what it actually is.</p>
<h3 id="heading-the-cgoenabled0-flag">The <code>CGO_ENABLED=0</code> Flag</h3>
<p>By default, Go can link against C libraries. When it does, the resulting binary depends on the system's C library being present at runtime. Alpine uses <code>musl</code> instead of the more common <code>glibc</code>, and that mismatch is a classic source of "works in the builder stage, crashes in the runtime stage" errors.</p>
<p>Setting <code>CGO_ENABLED=0</code> forces a pure-Go, fully static binary with no external library dependencies. It will run on any Linux system, including a <code>scratch</code> image with nothing in it at all.</p>
<h3 id="heading-copy-gomod-before-copy-maingo"><code>COPY go.mod .</code> Before <code>COPY main.go .</code></h3>
<p>Docker builds images layer by layer and caches each layer. By copying only <code>go.mod</code> first and running <code>go mod download</code> before copying the source code, we create a cached dependency layer.</p>
<p>On subsequent builds (and remember, this pipeline builds on <em>every commit to every open PR</em>), Docker skips the dependency download entirely as long as <code>go.mod</code> hasn't changed. On a real project with dozens of dependencies, this is the difference between a 20-second build and a 3-minute build, multiplied by every push your team makes.</p>
<h3 id="heading-the-non-root-user">The Non-Root User</h3>
<pre><code class="language-dockerfile">RUN addgroup -S appgroup &amp;&amp; adduser -S appuser -G appgroup
USER appuser
</code></pre>
<p>Containers run as root by default. If an attacker finds a vulnerability in your application, running as root inside the container gives them significantly more room to escalate. Creating an unprivileged user and switching to it limits the blast radius. It costs you two lines, and there's no reason not to do it.</p>
<p>Build and test it locally:</p>
<pre><code class="language-bash">docker build --build-arg PR_NUMBER=99 --build-arg GIT_SHA=abc1234 -t preview-app:test .
docker run -p 8080:8080 preview-app:test
</code></pre>
<p>Then <code>curl http://localhost:8080</code> in another terminal. You should now see <code>PR number : 99</code> and <code>Git SHA : abc1234</code>. The injection works.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/bce5bd63-02fc-4ee6-9631-34f810fad546.png" alt="Terminal output from curl showing the application reporting PR number 99 and Git SHA abc1234, injected at build time by the Docker build arguments" style="display: block;" width="2744" height="1256" loading="lazy">

<h2 id="heading-step-4-provision-the-infrastructure-with-terraform">Step 4: Provision the Infrastructure with Terraform</h2>
<p>Now we'll build the cloud infrastructure. We're using Terraform rather than a series of <code>gcloud</code> commands for a reason that becomes obvious the moment something goes wrong: with Terraform, <code>terraform destroy</code> cleans up everything you created, in the right order, with no orphaned resources quietly billing you.</p>
<p>Create <code>terraform/variables.tf</code>:</p>
<pre><code class="language-hcl">variable "project_id" {
  description = "GCP project ID"
  type        = string
}

variable "region" {
  description = "GCP region"
  type        = string
  default     = "europe-west2"
}

variable "zone" {
  description = "GCP zone. A zonal cluster is cheaper than a regional one."
  type        = string
  default     = "europe-west2-a"
}

variable "cluster_name" {
  description = "Name of the GKE cluster"
  type        = string
  default     = "pr-preview-cluster"
}

variable "github_repo" {
  description = "GitHub repository in owner/repo format, e.g. amina/pr-preview-envs"
  type        = string
}

variable "machine_type" {
  description = "Node machine type"
  type        = string
  default     = "e2-standard-2"
}

variable "node_count" {
  description = "Number of nodes in the pool"
  type        = number
  default     = 2
}
</code></pre>
<p>Now create <code>terraform/main.tf</code>:</p>
<pre><code class="language-hcl">terraform {
  required_version = "&gt;= 1.5"
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~&gt; 5.0"
    }
  }
}

provider "google" {
  project = var.project_id
  region  = var.region
}

# Look up the project so we can reference its numeric project number,
# which Workload Identity Federation requires (it doesn't accept the
# human-readable project ID).
data "google_project" "current" {}

# -----------------------------------------------------------
# Enable required APIs
# -----------------------------------------------------------
resource "google_project_service" "apis" {
  for_each = toset([
    "container.googleapis.com",
    "artifactregistry.googleapis.com",
    "iamcredentials.googleapis.com",
    "sts.googleapis.com",
  ])

  service            = each.value
  disable_on_destroy = false
}

# -----------------------------------------------------------
# Artifact Registry — where preview images live
# -----------------------------------------------------------
resource "google_artifact_registry_repository" "preview" {
  location      = var.region
  repository_id = "pr-preview"
  description   = "Container images for PR preview environments"
  format        = "DOCKER"

  depends_on = [google_project_service.apis]
}

# -----------------------------------------------------------
# GKE cluster
# -----------------------------------------------------------
resource "google_container_cluster" "primary" {
  name     = var.cluster_name
  location = var.zone

  # Create the cluster with a throwaway default pool, then remove it
  # and manage nodes through a separate node pool resource. This is the
  # standard pattern — it lets you resize or upgrade the node pool
  # without recreating the cluster control plane.
  remove_default_node_pool = true
  initial_node_count       = 1

  networking_mode = "VPC_NATIVE"
  ip_allocation_policy {}

  # Set to true before you use this for anything real.
  deletion_protection = false

  depends_on = [google_project_service.apis]
}

resource "google_container_node_pool" "primary_nodes" {
  name       = "${var.cluster_name}-pool"
  location   = var.zone
  cluster    = google_container_cluster.primary.name
  node_count = var.node_count

  node_config {
    machine_type = var.machine_type
    disk_size_gb = 50

    oauth_scopes = [
      "https://www.googleapis.com/auth/cloud-platform",
    ]

    labels = {
      purpose = "pr-preview-envs"
    }
  }

  management {
    auto_repair  = true
    auto_upgrade = true
  }
}
</code></pre>
<p>There are a few things that're worth calling out here.</p>
<p><code>data "google_project" "current"</code> isn't creating anything. It's a data source, which reads existing information from your provider. We need it because Workload Identity Federation identifies your project by its <strong>numeric project number</strong>, not the project ID you type in the console. Rather than making you look it up manually and paste it in, Terraform fetches it for you.</p>
<p><code>for_each</code> <strong>on</strong> <code>google_project_service</code>: instead of writing four nearly identical resource blocks to enable four APIs, <code>for_each</code> iterates over a set and creates one resource per item. <code>disable_on_destroy = false</code> means <code>terraform destroy</code> won't turn these APIs off, which is what you want, because other things in your project might be using them.</p>
<p><code>remove_default_node_pool = true</code>: GKE insists on creating a default node pool when you create a cluster. Setting this immediately deletes it, and we define our own node pool as a separate resource. The benefit is that node pool changes (resizing, changing machine type, upgrading) don't force a change to the cluster resource itself.</p>
<p><code>node_count = 2</code> <strong>with</strong> <code>e2-standard-2</code>: two nodes with 2 vCPU and 8GB each. Preview environments are small, but you'll have several running at once, plus GKE's own system pods. Two nodes give you comfortable headroom. If you plan to keep more than about eight preview environments alive simultaneously, bump this up.</p>
<p><code>deletion_protection = false</code>: GKE added this as a guard against accidentally destroying production clusters. We're disabling it because this is a tutorial cluster you'll delete at the end. If you adapt this for real use, set it to <code>true</code>.</p>
<h2 id="heading-step-5-set-up-keyless-authentication-with-workload-identity-federation">Step 5: Set Up Keyless Authentication with Workload Identity Federation</h2>
<p>This is the section that matters most, so let's take it slowly.</p>
<h3 id="heading-the-problem-with-service-account-keys">The Problem With Service Account Keys</h3>
<p>GitHub Actions needs permission to push images to Artifact Registry and deploy to your GKE cluster. The way most tutorials handle this is:</p>
<ol>
<li><p>Create a service account in GCP</p>
</li>
<li><p>Generate a JSON key for it</p>
</li>
<li><p>Paste that JSON into a GitHub secret called <code>GCP_SA_KEY</code></p>
</li>
<li><p>Load it in the workflow</p>
</li>
</ol>
<p>This works, but it's also a security problem, and here's why:</p>
<p>First, <strong>the key never expires.</strong> A service account JSON key is a long-lived credential. It's valid until someone explicitly revokes it, which in practice means it's valid forever, because nobody remembers to rotate them.</p>
<p>Second, <strong>the key is a bearer token.</strong> Anyone who obtains that JSON file <em>is</em> your service account. No second factor, IP restriction, or expiry. Copy the file, and use it from anywhere in the world.</p>
<p>Third, <strong>the blast radius is enormous.</strong> GitHub secrets are exposed to workflows. A compromised third-party action, a malicious dependency in your build, or a workflow modified in a pull request can exfiltrate that secret. Once it's out, an attacker has persistent access to your cloud project.</p>
<p>This isn't theoretical. Leaked service account keys are one of the most common root causes in cloud security incidents.</p>
<h3 id="heading-how-workload-identity-federation-fixes-it">How Workload Identity Federation Fixes It</h3>
<p><strong>Workload Identity Federation</strong> removes the long-lived key entirely. Here's the flow:</p>
<ol>
<li><p>GitHub Actions generates a short-lived <strong>OIDC token</strong> for the running workflow. This token is signed by GitHub and contains verified claims: which repository is running, which branch, which workflow, and which actor.</p>
</li>
<li><p>Your workflow presents that token to Google Cloud's Security Token Service.</p>
</li>
<li><p>Google checks the token's signature against GitHub's public keys, and checks the claims against rules <strong>you</strong> configured, specifically that the token came from your repository and no other.</p>
</li>
<li><p>If everything matches, Google issues a short-lived access token, typically valid for about an hour.</p>
</li>
<li><p>The workflow uses that token, and it expires shortly after.</p>
</li>
</ol>
<p>There's no secret stored anywhere. Nothing to leak, rotate, or revoke. If someone forks your repository and runs the same workflow, the OIDC token they generate will carry <em>their</em> repository name in its claims, Google's check will fail, and they get nothing.</p>
<p>Add this to <code>terraform/main.tf</code>:</p>
<pre><code class="language-hcl"># -----------------------------------------------------------
# Service account that GitHub Actions will impersonate
# -----------------------------------------------------------
resource "google_service_account" "github_actions" {
  account_id   = "github-actions-preview"
  display_name = "GitHub Actions — PR Preview Environments"
}

# Permission to push images to Artifact Registry
resource "google_project_iam_member" "artifact_writer" {
  project = var.project_id
  role    = "roles/artifactregistry.writer"
  member  = "serviceAccount:${google_service_account.github_actions.email}"
}

# Permission to create namespaces and deploy workloads in GKE.
# container.developer grants full access to Kubernetes API objects,
# but NOT permission to modify the cluster itself.
resource "google_project_iam_member" "gke_developer" {
  project = var.project_id
  role    = "roles/container.developer"
  member  = "serviceAccount:${google_service_account.github_actions.email}"
}

# -----------------------------------------------------------
# Workload Identity Federation
# -----------------------------------------------------------
resource "google_iam_workload_identity_pool" "github" {
  workload_identity_pool_id = "github-pool"
  display_name              = "GitHub Actions Pool"
  description               = "Identity pool for GitHub Actions OIDC"

  depends_on = [google_project_service.apis]
}

resource "google_iam_workload_identity_pool_provider" "github" {
  workload_identity_pool_id          = google_iam_workload_identity_pool.github.workload_identity_pool_id
  workload_identity_pool_provider_id = "github-provider"
  display_name                       = "GitHub OIDC Provider"

  # Map claims from the GitHub OIDC token to Google attributes
  attribute_mapping = {
    "google.subject"       = "assertion.sub"
    "attribute.actor"      = "assertion.actor"
    "attribute.repository" = "assertion.repository"
  }

  # CRITICAL: without this condition, ANY GitHub repository on the
  # internet could authenticate against your pool.
  attribute_condition = "assertion.repository == '${var.github_repo}'"

  oidc {
    issuer_uri = "https://token.actions.githubusercontent.com"
  }
}

# Allow tokens from your specific repo to impersonate the service account
resource "google_service_account_iam_member" "github_impersonation" {
  service_account_id = google_service_account.github_actions.name
  role               = "roles/iam.workloadIdentityUser"
  member             = "principalSet://iam.googleapis.com/projects/${data.google_project.current.number}/locations/global/workloadIdentityPools/${google_iam_workload_identity_pool.github.workload_identity_pool_id}/attribute.repository/${var.github_repo}"
}
</code></pre>
<p>Let's break down the parts that trip people up.</p>
<p><code>attribute_mapping</code>: GitHub's OIDC token contains a set of claims. This block tells Google which claims to read and what to call them internally. <code>assertion.sub</code> is the token's subject (something like <code>repo:owner/name:ref:refs/heads/main</code>). <code>assertion.repository</code> is the full repository name. <code>google.subject</code> is required, while the others are optional attributes you can then write rules against.</p>
<p><code>attribute_condition</code>: read this line twice, because getting it wrong is a serious vulnerability:</p>
<pre><code class="language-hcl">attribute_condition = "assertion.repository == '${var.github_repo}'"
</code></pre>
<p>Without this condition, your identity pool trusts <em>the GitHub OIDC issuer</em>, which means it trusts every repository on GitHub. Anyone who knows your pool's resource path (which isn't secret and appears in workflow files) could authenticate and impersonate your service account.</p>
<p>This condition narrows the trust to exactly one repository. Google now requires an attribute condition when you map <code>assertion.repository</code>, precisely because so many people got this wrong.</p>
<p><code>principalSet://...</code>: this is the identity being granted the <code>workloadIdentityUser</code> role. Read it right to left: any principal in the <code>github-pool</code> whose <code>attribute.repository</code> equals your repo may impersonate this service account. Note that it uses <code>data.google_project.current.number</code>, which is the numeric project number, not the project ID. Using the project ID here produces an error that doesn't clearly explain what's wrong, and it's one of the most common mistakes with WIF.</p>
<p><strong>Why</strong> <code>roles/container.developer</code> <strong>and not</strong> <code>roles/container.admin</code><strong>?</strong> <code>container.developer</code> grants full access to Kubernetes API objects inside clusters: creating namespaces, applying deployments, deleting resources. <code>container.admin</code> additionally allows modifying the clusters themselves: resizing node pools, upgrading, deleting the cluster entirely.</p>
<p>Our workflow never needs to touch the cluster's own configuration, so it shouldn't have permission to. This is least privilege in practice: grant exactly what the job requires and nothing beyond it.</p>
<p>Now create <code>terraform/outputs.tf</code>:</p>
<pre><code class="language-hcl">output "cluster_name" {
  value = google_container_cluster.primary.name
}

output "cluster_zone" {
  value = var.zone
}

output "artifact_registry_url" {
  description = "Base URL for pushing images"
  value       = "${var.region}-docker.pkg.dev/${var.project_id}/${google_artifact_registry_repository.preview.repository_id}"
}

output "workload_identity_provider" {
  description = "Paste this into the GitHub Actions workflow"
  value       = "projects/${data.google_project.current.number}/locations/global/workloadIdentityPools/${google_iam_workload_identity_pool.github.workload_identity_pool_id}/providers/${google_iam_workload_identity_pool_provider.github.workload_identity_pool_provider_id}"
}

output "service_account_email" {
  description = "Paste this into the GitHub Actions workflow"
  value       = google_service_account.github_actions.email
}

output "get_credentials_command" {
  value = "gcloud container clusters get-credentials ${google_container_cluster.primary.name} --zone ${var.zone} --project ${var.project_id}"
}
</code></pre>
<p>Those outputs aren't decoration. <code>workload_identity_provider</code> and <code>service_account_email</code> are the two values you'll paste into your GitHub Actions workflow, and both are tedious to construct by hand.</p>
<h2 id="heading-step-6-apply-the-terraform-configuration">Step 6: Apply the Terraform Configuration</h2>
<p>From inside the <code>terraform/</code> directory:</p>
<pre><code class="language-bash">terraform init
</code></pre>
<p>This downloads the Google provider and sets up the backend. You should see "Terraform has been successfully initialized!"</p>
<p>Now preview what will be created:</p>
<pre><code class="language-bash">terraform plan \
  -var="project_id=YOUR_PROJECT_ID" \
  -var="github_repo=YOUR_USERNAME/pr-preview-envs"
</code></pre>
<p>Read the plan output. Terraform tells you exactly what it intends to create before it creates anything. You should see roughly a dozen resources to add and none to change or destroy.</p>
<p>If that looks right:</p>
<pre><code class="language-bash">terraform apply \
  -var="project_id=YOUR_PROJECT_ID" \
  -var="github_repo=YOUR_USERNAME/pr-preview-envs"
</code></pre>
<p>Type <code>yes</code> when prompted. Cluster creation takes about five minutes.</p>
<p><strong>Tip:</strong> typing those <code>-var</code> flags repeatedly gets old fast. Create a file called <code>terraform.tfvars</code> containing <code>project_id = "your-project-id"</code> and <code>github_repo = "you/pr-preview-envs"</code>, and Terraform picks it up automatically. Add it to <code>.gitignore</code>.</p>
<p>When it finishes, Terraform prints your outputs. <strong>Save these</strong>, as you'll need them in Step 9:</p>
<pre><code class="language-plaintext">artifact_registry_url = "europe-west2-docker.pkg.dev/your-project/pr-preview"
service_account_email = "github-actions-preview@your-project.iam.gserviceaccount.com"
workload_identity_provider = "projects/123456789/locations/global/workloadIdentityPools/github-pool/providers/github-provider"
</code></pre>
<p>You can print them again any time with <code>terraform output</code>.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/23a9ff48-3691-41c5-876f-83cfdf226909.png" alt="Output of Terraform apply showing credentials needed" style="display: block;" width="2744" height="1454" loading="lazy">

<p>Connect <code>kubectl</code> to the new cluster using the command from the <code>get_credentials_command</code> output:</p>
<pre><code class="language-bash">gcloud container clusters get-credentials pr-preview-cluster \
  --zone europe-west2-a \
  --project YOUR_PROJECT_ID
</code></pre>
<p>Verify:</p>
<pre><code class="language-bash">kubectl get nodes
</code></pre>
<p>You should see two nodes in <code>Ready</code> state.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/cbfcf36b-9e9a-4d38-8165-3c1327e3b0f6.png" alt="Output of kubectl get nodes showing two GKE nodes in Ready status" style="display: block;" width="2744" height="416" loading="lazy">

<h2 id="heading-step-7-prove-the-lifecycle-manually">Step 7: Prove the Lifecycle Manually</h2>
<p>Before automating anything, do it by hand once.</p>
<p>This isn't busywork. Automation is fundamentally just a script running commands you could have typed. If you don't know what the commands are, you can't debug the automation when it fails...and it will fail, usually at 11 pm before a demo. Ten minutes here saves hours later.</p>
<p>Create a namespace:</p>
<pre><code class="language-bash">kubectl create namespace pr-test
</code></pre>
<p>Deploy a placeholder into it:</p>
<pre><code class="language-bash">kubectl create deployment hello \
  --image=nginx:1.27-alpine \
  --namespace=pr-test
</code></pre>
<p>Check it:</p>
<pre><code class="language-bash">kubectl get pods --namespace=pr-test
</code></pre>
<p>Now the important part – prove the isolation:</p>
<pre><code class="language-bash">kubectl get pods --all-namespaces | grep hello
</code></pre>
<p>The pod exists only in <code>pr-test</code>. Nothing in <code>default</code> or any other namespace knows about it. That's the property the entire project is built on: a namespace is a boundary, and everything inside one PR's namespace is invisible to every other.</p>
<p>Now tear it down:</p>
<pre><code class="language-bash">kubectl delete namespace pr-test
</code></pre>
<p>Watch what happens:</p>
<pre><code class="language-bash">kubectl get namespace pr-test
</code></pre>
<p>For a few seconds, you'll see <code>Terminating</code>, then the namespace disappears entirely. Deleting a namespace deletes every resource inside it: deployments, pods, services, config maps, secrets, everything. One command, complete cleanup.</p>
<p>That single property is why namespace-per-PR is such a good fit for preview environments. Teardown isn't a careful sequence of deletions you have to get right. It's one command that can't leave anything behind.</p>
<h2 id="heading-step-8-write-the-kubernetes-manifests-with-kustomize">Step 8: Write the Kubernetes Manifests with Kustomize</h2>
<p>Every preview environment deploys the same application. The only differences between <code>pr-42</code> and <code>pr-43</code> are the namespace and the image tag.</p>
<p>This is exactly the problem <strong>Kustomize</strong> solves. You write the manifests once as a <strong>base</strong>, then apply small, declarative changes on top of it (an <strong>overlay</strong>) without templating, string substitution, or <code>sed</code> scripts mangling your YAML.</p>
<p>Kustomize is built into <code>kubectl</code> (that's the <code>-k</code> flag), so there's nothing extra to install.</p>
<p>Create <code>k8s/base/deployment.yaml</code>:</p>
<pre><code class="language-yaml">apiVersion: apps/v1
kind: Deployment
metadata:
  name: preview-app
  labels:
    app: preview-app
spec:
  replicas: 1
  selector:
    matchLabels:
      app: preview-app
  template:
    metadata:
      labels:
        app: preview-app
    spec:
      containers:
        - name: preview-app
          # This is a placeholder. The overlay replaces it with the
          # real registry path and PR-specific tag.
          image: preview-app
          ports:
            - containerPort: 8080
          env:
            # Downward API: the pod learns its own identity
            - name: POD_NAMESPACE
              valueFrom:
                fieldRef:
                  fieldPath: metadata.namespace
            - name: POD_NAME
              valueFrom:
                fieldRef:
                  fieldPath: metadata.name
          livenessProbe:
            httpGet:
              path: /healthz
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /healthz
              port: 8080
            initialDelaySeconds: 2
            periodSeconds: 5
          resources:
            requests:
              cpu: "50m"
              memory: "64Mi"
            limits:
              cpu: "200m"
              memory: "128Mi"
</code></pre>
<p>Create <code>k8s/base/service.yaml</code>:</p>
<pre><code class="language-yaml">apiVersion: v1
kind: Service
metadata:
  name: preview-app
spec:
  selector:
    app: preview-app
  ports:
    - protocol: TCP
      port: 80
      targetPort: 8080
  type: ClusterIP
</code></pre>
<p>Create <code>k8s/base/kustomization.yaml</code>:</p>
<pre><code class="language-yaml">apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - deployment.yaml
  - service.yaml
</code></pre>
<p>There are some deliberate choices here.</p>
<p><code>replicas: 1</code>: production runs multiple replicas for availability. A preview environment doesn't need high availability. One replica per environment, multiplied across every open PR, keeps your node count and your bill sane.</p>
<p><code>image: preview-app</code>: a bare placeholder with no registry and no tag. It would never pull as-is. Kustomize's image transformer matches on this name and replaces it wholesale, so the base manifest never needs to know your registry URL.</p>
<p><strong>The Downward API</strong> <code>env</code> <strong>block</strong>: this is where <code>POD_NAMESPACE</code> and <code>POD_NAME</code> come from. <code>fieldRef</code> reads a field from the pod's own spec at runtime and exposes it as an environment variable. No API calls, credentials, or service account needed.</p>
<p><code>type: ClusterIP</code>: internal-only. Each <code>LoadBalancer</code> service provisions a real Google Cloud load balancer with a real hourly cost and a public IP. Doing that per PR would be expensive and wasteful. We'll reach the app with <code>kubectl port-forward</code> for now, and in Step 13 a single shared Ingress controller takes over, serving every environment through one load balancer.</p>
<p><strong>Resource requests and limits</strong>: <code>requests</code> reserve capacity so the scheduler knows how much room a pod needs. <code>limits</code> cap what it can consume. Without limits, one runaway preview environment could starve every other one on the node. With many short-lived environments coming and going, this isn't optional.</p>
<p>Test the base renders correctly:</p>
<pre><code class="language-bash">kubectl kustomize k8s/base
</code></pre>
<p>That prints the rendered YAML without applying it. This is useful for debugging.</p>
<h2 id="heading-step-9-build-the-spin-up-workflow">Step 9: Build the Spin-Up Workflow</h2>
<p>Now we connect everything.</p>
<p>Create <code>.github/workflows/preview-deploy.yml</code>:</p>
<pre><code class="language-yaml">name: Deploy PR Preview

on:
  pull_request:
    types: [opened, synchronize, reopened]

# If someone pushes three commits quickly, cancel the older runs.
# Without this, three deploys race each other into the same namespace
# and whichever finishes last wins — which may not be the newest commit.
concurrency:
  group: preview-${{ github.event.pull_request.number }}
  cancel-in-progress: true

permissions:
  contents: read
  id-token: write   # REQUIRED for Workload Identity Federation
  pull-requests: write

env:
  PROJECT_ID: YOUR_PROJECT_ID
  REGION: europe-west2
  CLUSTER_NAME: pr-preview-cluster
  CLUSTER_ZONE: europe-west2-a
  REPOSITORY: pr-preview
  IMAGE_NAME: preview-app

jobs:
  deploy:
    name: Build and deploy preview
    runs-on: ubuntu-latest

    steps:
      - name: Check out code
        uses: actions/checkout@v4

      - name: Set environment variables
        run: |
          PR_NUMBER=${{ github.event.pull_request.number }}
          SHORT_SHA=$(echo "${{ github.event.pull_request.head.sha }}" | cut -c1-7)

          echo "PR_NUMBER=${PR_NUMBER}"   &gt;&gt; $GITHUB_ENV
          echo "SHORT_SHA=${SHORT_SHA}"   &gt;&gt; $GITHUB_ENV
          echo "NAMESPACE=pr-${PR_NUMBER}" &gt;&gt; $GITHUB_ENV
          echo "IMAGE_TAG=pr-${PR_NUMBER}-${SHORT_SHA}" &gt;&gt; $GITHUB_ENV
          echo "IMAGE_BASE=${{ env.REGION }}-docker.pkg.dev/${{ env.PROJECT_ID }}/${{ env.REPOSITORY }}/${{ env.IMAGE_NAME }}" &gt;&gt; $GITHUB_ENV

      - name: Authenticate to Google Cloud
        uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: ${{ secrets.WIF_PROVIDER }}
          service_account: ${{ secrets.WIF_SERVICE_ACCOUNT }}

      - name: Set up gcloud
        uses: google-github-actions/setup-gcloud@v2

      - name: Configure Docker for Artifact Registry
        run: gcloud auth configure-docker ${{ env.REGION }}-docker.pkg.dev --quiet

      - name: Build and push image
        run: |
          docker build \
            --build-arg PR_NUMBER="${PR_NUMBER}" \
            --build-arg GIT_SHA="${SHORT_SHA}" \
            -t "${IMAGE_BASE}:${IMAGE_TAG}" \
            ./app

          docker push "${IMAGE_BASE}:${IMAGE_TAG}"

      - name: Get GKE credentials
        uses: google-github-actions/get-gke-credentials@v2
        with:
          cluster_name: ${{ env.CLUSTER_NAME }}
          location: ${{ env.CLUSTER_ZONE }}

      - name: Create namespace
        run: |
          # --dry-run=client | apply makes this idempotent.
          # Running it on an existing namespace is a no-op, not an error.
          kubectl create namespace "${NAMESPACE}" \
            --dry-run=client -o yaml | kubectl apply -f -

      - name: Generate Kustomize overlay
        run: |
          mkdir -p k8s/overlays/"${NAMESPACE}"
          cat &gt; k8s/overlays/"${NAMESPACE}"/kustomization.yaml &lt;&lt;EOF
          apiVersion: kustomize.config.k8s.io/v1beta1
          kind: Kustomization

          namespace: ${NAMESPACE}

          resources:
            - ../../base

          images:
            - name: preview-app
              newName: ${IMAGE_BASE}
              newTag: ${IMAGE_TAG}
          EOF

          echo "--- Rendered manifest ---"
          kubectl kustomize k8s/overlays/"${NAMESPACE}"

      - name: Deploy
        run: kubectl apply -k k8s/overlays/"${NAMESPACE}"

      - name: Wait for rollout
        run: |
          kubectl rollout status deployment/preview-app \
            --namespace="${NAMESPACE}" \
            --timeout=180s

      - name: Show deployment details
        run: |
          echo "Namespace: ${NAMESPACE}"
          kubectl get pods,svc --namespace="${NAMESPACE}"
</code></pre>
<h3 id="heading-add-the-two-secrets">Add the Two Secrets</h3>
<p>Go to your repository on GitHub and go to <strong>Settings</strong>, <strong>Secrets and variables</strong>, <strong>Actions</strong>, and <strong>New repository secret</strong>. Add:</p>
<table>
<thead>
<tr>
<th>Secret name</th>
<th>Value</th>
</tr>
</thead>
<tbody><tr>
<td><code>WIF_PROVIDER</code></td>
<td>The <code>workload_identity_provider</code> output from Terraform</td>
</tr>
<tr>
<td><code>WIF_SERVICE_ACCOUNT</code></td>
<td>The <code>service_account_email</code> output from Terraform</td>
</tr>
</tbody></table>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/3badb7bc-a162-4db7-ae18-5c93b492c5cc.png" alt="GitHub repository secrets page listing WIF_PROVIDER and WIF_SERVICE_ACCOUNT" style="display: block;" width="2380" height="1446" loading="lazy">

<p>Neither of these is a credential. The provider path and service account email are identifiers, not secrets. They grant nothing on their own, because the OIDC token and the attribute condition are what actually control access. Storing them as secrets is just tidiness. Update <code>PROJECT_ID</code> and the region values in the workflow's <code>env:</code> block to match your setup.</p>
<h3 id="heading-understanding-the-workflow">Understanding the Workflow</h3>
<p><code>on: pull_request: types: [opened, synchronize, reopened]</code>: these are three distinct triggers.</p>
<ul>
<li><p><code>opened</code> fires when the PR is first created.</p>
</li>
<li><p><code>synchronize</code> fires on every subsequent push to the branch, which is what keeps the environment current.</p>
</li>
<li><p><code>reopened</code> handles a PR that was closed and then reopened. Without it, that PR would have a torn-down environment and nothing to recreate it.</p>
</li>
</ul>
<p><code>concurrency</code>: this one saves real debugging time. Push three commits in quick succession, and you get three workflow runs targeting the same namespace. They race. The one that finishes last wins, and that's not necessarily the newest code. A fast early build can overtake a slow later one, leaving your preview environment silently running stale code while the PR shows green. Grouping by PR number with <code>cancel-in-progress: true</code> means only the newest run survives.</p>
<p><code>permissions: id-token: write</code>: without this line, nothing else works. It's what allows the workflow to request an OIDC token from GitHub. Leave it out and <code>google-github-actions/auth</code> fails with an error about being unable to get an ID token. This is the single most common WIF setup mistake.</p>
<p><code>$GITHUB_ENV</code>: writing <code>KEY=value</code> to this file makes the variable available in all <em>subsequent</em> steps. Not the current one, as a variable you write in a step can't be read later in that same step. It's why the setup happens in its own step at the top.</p>
<p><code>github.event.pull_request.head.sha</code>: note this rather than <code>github.sha</code>. On <code>pull_request</code> events, GitHub checks out a <em>merge commit</em>. This is a temporary commit combining your branch with the base branch. <code>github.sha</code> refers to that merge commit, which doesn't exist in your repository's history and will confuse anyone who tries to look it up. <code>head.sha</code> is the actual last commit on the PR branch, which is what a developer expects to see.</p>
<p><code>--dry-run=client -o yaml | kubectl apply -f -</code> is a small trick worth stealing. <code>kubectl create namespace</code> fails if the namespace already exists, which would break every push after the first. This pipeline generates the namespace YAML without contacting the cluster, then pipes it to<code>apply</code>, which creates it if it's missing and does nothing if it isn't. Idempotent by construction.</p>
<p><strong>The heredoc overlay</strong>: instead of committing an overlay per PR (impossible, as you don't know PR numbers in advance), the workflow writes one at runtime and throws it away when the runner is destroyed. It's ephemeral configuration for an ephemeral environment.</p>
<p><code>kubectl rollout status</code> is what makes the workflow honest. Without it, the job succeeds the moment <code>kubectl apply</code> is accepted by the API server, which happens before a single pod has started. A crash-looping image would still show a green check. <code>rollout status</code> blocks until pods are actually ready, or fails after 180 seconds. Green means working.</p>
<h3 id="heading-a-note-on-forked-pull-requests">A Note on Forked Pull Requests</h3>
<p>Something is worth knowing before you deploy this anywhere public: pull requests from forks do <strong>not</strong> receive <code>id-token: write</code> permission, by design. GitHub blocks it so a stranger can't open a PR that steals your cloud credentials.</p>
<p>For a private repository or a personal project, this doesn't affect you. For a public repository accepting outside contributions, you'd need a <code>workflow_run</code>-based pattern where a privileged workflow runs from the base repository after the untrusted build completes. That's beyond this handbook's scope, but if you're deploying this on an open-source project, don't skip it.</p>
<h2 id="heading-step-10-build-the-teardown-workflow">Step 10: Build the Teardown Workflow</h2>
<p>Spin-up is only half the value. An environment that never disappears is just a slow leak in your cloud bill.</p>
<p>Create <code>.github/workflows/preview-teardown.yml</code>:</p>
<pre><code class="language-yaml">name: Tear Down PR Preview

on:
  pull_request:
    types: [closed]

permissions:
  contents: read
  id-token: write

env:
  PROJECT_ID: YOUR_PROJECT_ID
  CLUSTER_NAME: pr-preview-cluster
  CLUSTER_ZONE: europe-west2-a

jobs:
  teardown:
    name: Delete preview namespace
    runs-on: ubuntu-latest

    steps:
      - name: Set namespace
        run: echo "NAMESPACE=pr-${{ github.event.pull_request.number }}" &gt;&gt; $GITHUB_ENV

      - name: Authenticate to Google Cloud
        uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: ${{ secrets.WIF_PROVIDER }}
          service_account: ${{ secrets.WIF_SERVICE_ACCOUNT }}

      - name: Get GKE credentials
        uses: google-github-actions/get-gke-credentials@v2
        with:
          cluster_name: ${{ env.CLUSTER_NAME }}
          location: ${{ env.CLUSTER_ZONE }}

      - name: Delete namespace
        run: |
          echo "Deleting namespace ${NAMESPACE}"
          kubectl delete namespace "${NAMESPACE}" \
            --ignore-not-found=true \
            --wait=false

      - name: Confirm
        run: |
          echo "Preview environment for PR #${{ github.event.pull_request.number }} torn down."
</code></pre>
<p>A few details here matter more than they might seem.</p>
<p>First, <code>types: [closed]</code> <strong>covers merges too.</strong> GitHub doesn't have a separate <code>merged</code> event type. Merging a pull request fires <code>closed</code> with the payload field <code>merged: true</code>. So this single trigger handles both "merged successfully" and "abandoned and closed." Both should tear down the environment, so we don't need to distinguish between them.</p>
<p>Next, <code>--ignore-not-found=true</code>: if the namespace doesn't exist (perhaps the deploy failed, or someone deleted it manually), <code>kubectl delete</code> would normally exit with an error and mark the workflow red. That's a false alarm: the desired end state is "namespace doesn't exist," and it doesn't. This flag makes the step succeed when there's nothing to do.</p>
<p>Finally, <code>--wait=false</code>: namespace deletion is asynchronous. Kubernetes marks it<code>Terminating</code>, then works through deleting every resource inside it. Waiting for that to complete could hold your CI runner for a minute or more, for no benefit. Fire the delete and let the cluster finish on its own time.</p>
<h2 id="heading-step-11-open-a-pull-request-and-watch-it-work">Step 11: Open a Pull Request and Watch It Work</h2>
<p>Commit everything and push:</p>
<pre><code class="language-bash">git add .
git commit -m "Add PR preview environment infrastructure"
git push -u origin main
</code></pre>
<p>Now create a branch and make a visible change:</p>
<pre><code class="language-bash">git checkout -b test-preview
</code></pre>
<p>Edit <code>app/main.go</code>. Change the first line of the handler output:</p>
<pre><code class="language-go">fmt.Fprintf(w, "Preview environment is live — testing the pipeline\n\n")
</code></pre>
<p>Commit and push:</p>
<pre><code class="language-bash">git add .
git commit -m "Test preview environment"
git push -u origin test-preview
</code></pre>
<p>Open a pull request on GitHub, then go to the <strong>Actions</strong> tab. You should see "Deploy PR Preview" running.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/4da5dcda-506a-4a9d-8413-5c5cd32af0c1.png" alt="GitHub Actions summary for a pull request showing the Deploy PR Preview workflow completed successfully" style="display: block;" width="2380" height="1446" loading="lazy">

<p>Watch the steps in order: authentication succeeds without a key, the image builds and pushes, the namespace is created, Kustomize renders the overlay (you'll see the fully resolved manifest printed), the deployment applies, and <code>rollout status</code> waits until pods are ready.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/3f0ae123-82fb-447e-9a5a-db1e87589340.png" alt="Expanded GitHub Actions log showing the deploy, wait for rollout, and show deployment details steps completing successfully" style="display: block;" width="2380" height="1446" loading="lazy">

<p>Once it's green, verify from your terminal:</p>
<pre><code class="language-shell">kubectl get namespaces | grep pr-
</code></pre>
<p>You should see your <code>pr-1</code> (or whatever number your PR got).</p>
<pre><code class="language-shell">kubectl get pods --namespace=pr-1
</code></pre>
<p>Now reach the application:</p>
<pre><code class="language-shell">kubectl port-forward --namespace=pr-1 service/preview-app 8080:80
</code></pre>
<p>In a second terminal:</p>
<pre><code class="language-shell">curl http://localhost:8080
</code></pre>
<p>You should see:</p>
<pre><code class="language-shell">Preview environment is live — testing the pipeline

PR number  : 1
Git SHA    : a1b2c3d
Namespace  : pr-1
Pod name   : preview-app-7d9f8b6c4-xk2mp
</code></pre>
<p>The application is reporting the PR number and commit SHA that were baked into its binary at build time, and the namespace it discovered through the Downward API. Every one of those values was resolved by a different part of the pipeline, and they all agree. That's your proof the whole chain works.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/17b0712a-0fa3-47be-8078-67663239acfe.png" alt="Terminal output from curl showing the preview environment reporting PR number 1, its commit SHA, namespace pr-1, and the pod name" style="display: block;" width="1266" height="1012" loading="lazy">

<p>Now push another commit to the same branch and watch the environment update in place.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/2ca76645-9fe0-491d-8dae-05789a6b5498.png" alt="GitHub Actions log showing the Deploy PR Preview workflow running again after a second commit was pushed to the same branch" style="display: block;" width="2372" height="1012" loading="lazy">

<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/426cc240-5ee7-487b-9fe4-dc955b06ac31.png" alt="Terminal showing kubectl port-forward running against namespace pr-1 alongside the curl command used to reach it" style="display: block;" width="1870" height="554" loading="lazy">

<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/a66c098b-b972-4282-8f84-6f4ab49fc34b.png" alt="Terminal output from curl showing the updated greeting text and new commit SHA after the second push, confirming the environment redeployed in place" style="display: block;" width="1870" height="646" loading="lazy">

<p>Then close the pull request and watch the teardown workflow fire.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/bbcacedc-2ade-4945-b849-fd6be8931819.png" alt="GitHub Actions teardown workflow triggered and in progress" style="display: block;" width="2378" height="864" loading="lazy">

<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/4b5fb004-ebb6-424c-a535-caa9f8037265.png" alt="GitHub Actions teardown workflow completing" style="display: block;" width="2378" height="1438" loading="lazy">

<pre><code class="language-bash">kubectl get namespace pr-1
</code></pre>
<p><code>Terminating</code>, then gone.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/8d373dd3-f627-400c-aad2-9a845b549ce5.png" alt="Terminal output showing kubectl get namespace returning &quot;namespaces pr-1 not found&quot;" style="display: block;" width="2378" height="158" loading="lazy">

<h3 id="heading-what-you-have-and-whats-still-missing">What You Have, and What's Still Missing</h3>
<p>Stop and take stock, because the hard infrastructure work is done. A pull request now produces a real, isolated environment with no manual steps, and closing it removes every trace. That's the whole lifecycle, automated.</p>
<p>But look again at how you reached it:</p>
<pre><code class="language-plaintext">kubectl port-forward --namespace=pr-1 service/preview-app 8080:80
</code></pre>
<p>That requires <code>kubectl</code> installed, credentials for the cluster, permission to use them, and knowledge of which namespace maps to which PR. This is fine for the person who built the pipeline, but it's useless for the designer checking a spacing change, the product manager reviewing a copy edit, or the QA engineer clicking through a flow before sign-off.</p>
<p>The whole point of a preview environment is that <em><strong>anyone</strong></em> can look at the change. An environment only engineers can reach isn't really a preview environment. It's a debugging tool.</p>
<p>The rest of this tutorial closes that gap, and then makes the result safe to leave running. First, we'll set up a public HTTPS URL for every environment. Then we'll build the guardrails and go through the cleanup that stop it becoming a quiet line item on your cloud bill.</p>
<h2 id="heading-step-12-reserve-a-static-ip-address">Step 12: Reserve a Static IP Address</h2>
<p>Before installing anything, you'll need to reserve an external IP address.</p>
<p>This matters because when you install the Ingress controller, it creates a Kubernetes Service of type <code>LoadBalancer</code>, and Google Cloud provisions a real load balancer with a public IP. By default, that IP is <strong>ephemeral</strong>. If the Service is deleted and recreated, you get a different one.</p>
<p>Your wildcard DNS record points at that IP. If it changes, every preview environment breaks at once, and you won't find out until someone tells you the link is dead. Reserving the IP first means it belongs to your project, not to the load balancer, and it survives anything you do to the cluster.</p>
<p>Add this to <code>terraform/main.tf</code>:</p>
<pre><code class="language-hcl"># -----------------------------------------------------------
# Static external IP for the Ingress controller
# -----------------------------------------------------------
resource "google_compute_address" "ingress" {
  name         = "pr-preview-ingress-ip"
  region       = var.region
  address_type = "EXTERNAL"

  depends_on = [google_project_service.apis]
}
</code></pre>
<p>And add the output to <code>terraform/outputs.tf</code>:</p>
<pre><code class="language-hcl">output "ingress_ip" {
  description = "Point your wildcard DNS record at this address"
  value       = google_compute_address.ingress.address
}
</code></pre>
<p>You'll also want <code>compute.googleapis.com</code> in the APIs list if it isn't there already. Update the <code>for_each</code> set in your <code>google_project_service</code> resource:</p>
<pre><code class="language-hcl">  for_each = toset([
    "container.googleapis.com",
    "artifactregistry.googleapis.com",
    "iamcredentials.googleapis.com",
    "sts.googleapis.com",
    "compute.googleapis.com",
  ])
</code></pre>
<p>Apply it:</p>
<pre><code class="language-bash">cd terraform
terraform apply \
  -var="project_id=YOUR_PROJECT_ID" \
  -var="github_repo=YOUR_USERNAME/pr-preview-envs"
</code></pre>
<p>Note the IP that comes back:</p>
<pre><code class="language-bash">terraform output ingress_ip
</code></pre>
<p>Write it down. You'll use it twice in the next two steps.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/a9b0586d-3b1e-4fe2-9eb4-53087b70a45a.png" alt="terraform output ingress_ip showing the reserved address" style="display: block;" width="2378" height="1056" loading="lazy">

<p><strong>Important:</strong> this must be a <strong>regional</strong> address in the same region as your cluster, which is what <code>region = var.region</code> gives you. Google Cloud also offers global addresses, used by global HTTP(S) load balancers.</p>
<p>The Service type <code>LoadBalancer</code> that ingress-nginx creates is a regional load balancer, and it can't bind a global address. Mixing these up produces a Service stuck in <code>Pending</code> forever with an error that doesn't clearly explain why.</p>
<h2 id="heading-step-13-install-the-ingress-controller">Step 13: Install the Ingress Controller</h2>
<p>An <strong>Ingress</strong> is a Kubernetes resource that describes HTTP routing rules: "requests for this hostname go to that Service." But the Ingress resource is only a description. Something has to actually read those rules and route traffic, and that something is an <strong>Ingress controller</strong>.</p>
<p>We'll use <strong>ingress-nginx</strong>, which is the community-maintained controller built on NGINX. It runs as pods in your cluster, watches the Kubernetes API for Ingress resources, and rewrites its own NGINX configuration whenever one changes.</p>
<p>The architectural point that makes this work for preview environments is that <strong>one controller serves every namespace</strong>. Each preview environment creates its own Ingress resource. The controller picks it up, adds a routing rule for that hostname, and sends traffic to the right Service. The controller doesn't care how many environments exist.</p>
<p>Contrast this with what we'd otherwise do. If each preview environment used a <code>LoadBalancer</code> Service, every PR would provision its own Google Cloud load balancer, each with an hourly charge and its own IP address that DNS would need to know about. Ten open PRs would mean ten load balancers. With a shared Ingress controller, ten open PRs mean one.</p>
<p>Install it with Helm:</p>
<pre><code class="language-bash">helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update

helm install ingress-nginx ingress-nginx/ingress-nginx \
  --namespace ingress-nginx \
  --create-namespace \
  --set controller.service.loadBalancerIP="YOUR_STATIC_IP" \
  --set controller.service.externalTrafficPolicy=Local
</code></pre>
<p>Replace <code>YOUR_STATIC_IP</code> with the address from Step 12.</p>
<p>Let's break down the flags before we go on:</p>
<p><code>--namespace ingress-nginx --create-namespace</code>: the controller gets its own namespace, separate from any preview environment. It's shared infrastructure, and it should never be caught up in a preview environment's teardown.</p>
<p><code>controller.service.loadBalancerIP</code>: tells GKE to bind the load balancer to the specific address you reserved, rather than allocating a new one. This is the line that makes your DNS record stable.</p>
<p><code>controller.service.externalTrafficPolicy=Local</code>: preserves the client's real source IP. Without it, Kubernetes may route a request through an intermediate node, and by the time it reaches NGINX the source IP has been rewritten to a node's internal address. Your access logs would show cluster IPs instead of real visitors.</p>
<p>The tradeoff is that traffic only lands on nodes actually running a controller pod, which is fine here.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/7813b917-231e-44fc-9d5b-9501c1745145.png" alt="Terminal output from helm install showing the ingress-nginx chart deployed successfully into the ingress-nginx namespace" style="display: block;" width="2768" height="1420" loading="lazy">

<p>Watch for the external IP to be assigned:</p>
<pre><code class="language-bash">kubectl get service ingress-nginx-controller \
  --namespace ingress-nginx \
  --watch
</code></pre>
<p>It shows <code>&lt;pending&gt;</code> for a minute or two while Google provisions the load balancer, then displays your static IP from Step 12. Press Ctrl+C once it appears.</p>
<p>Verify that the controller is healthy:</p>
<pre><code class="language-bash">kubectl get pods --namespace ingress-nginx
</code></pre>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/f38b8e9c-d7e6-4c18-b5ac-927aef24118f.png" alt="Output of kubectl get service and kubectl get pods showing the ingress-nginx controller running with the reserved static external IP assigned" style="display: block;" width="2768" height="1420" loading="lazy">

<h2 id="heading-step-14-point-wildcard-dns-at-the-load-balancer">Step 14: Point Wildcard DNS at the Load Balancer</h2>
<p>This step takes about two minutes and is the piece that makes the whole pattern scale.</p>
<p>Go to wherever your domain's DNS is managed and create a single <strong>A record</strong>:</p>
<table>
<thead>
<tr>
<th>Field</th>
<th>Value</th>
</tr>
</thead>
<tbody><tr>
<td>Type</td>
<td><code>A</code></td>
</tr>
<tr>
<td>Name / Host</td>
<td><code>*.preview</code></td>
</tr>
<tr>
<td>Value</td>
<td>Your static IP from Step 1</td>
</tr>
<tr>
<td>TTL</td>
<td>300 (or the lowest your provider allows)</td>
</tr>
</tbody></table>
<p>That's it. That's the entire DNS configuration for the project.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/461ad5af-b55e-4ec4-912a-0fac144a4db5.png" alt="DNS provider interface showing a wildcard A record for *.preview pointing to the static IP address of the ingress load balancer" style="display: block;" width="1892" height="1172" loading="lazy">

<p>Here's why one record is enough. A wildcard DNS record matches <strong>any</strong> label in that position. <code>*.preview.yourdomain.com</code> resolves <code>pr-1.preview.yourdomain.com</code>, <code>pr-42.preview.yourdomain.com</code>, and <code>pr-99999.preview.yourdomain.com</code>, all to the same IP, all without anyone creating a record for them.</p>
<p>This is worth pausing on, because it's the design decision that keeps the system simple. The obvious approach would be to have the CI pipeline create a DNS record when a PR opens and delete it when the PR closes. That means DNS API credentials in your pipeline, another thing to fail, another thing to leak, and another source of orphaned resources.</p>
<p>The wildcard approach eliminates that entire category of work: DNS is configured once, manually, and never touched again.</p>
<p>Routing to the right environment doesn't happen in DNS. Every hostname resolves to the same load balancer, and the Ingress controller reads the <code>Host</code> header of each incoming request to decide which namespace's Service should handle it.</p>
<p>Verify the record has propagated:</p>
<pre><code class="language-bash">dig +short anything-at-all.preview.yourdomain.com
</code></pre>
<p>You should get your static IP back. Note that the subdomain doesn't need to exist yet. That's the whole point of a wildcard.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/a11681bf-5899-47b5-9731-f45096915f02.png" alt="Terminal output from dig returning the ingress static IP for a subdomain that was never explicitly created, confirming the wildcard record resolves" style="display: block;" width="1892" height="152" loading="lazy">

<p>If nothing comes back, wait a few minutes and try again. DNS propagation is usually fast with a low TTL, but it isn't instant.</p>
<h2 id="heading-step-15-install-cert-manager-and-create-a-clusterissuer">Step 15: Install cert-manager and Create a ClusterIssuer</h2>
<p>Now for HTTPS.</p>
<p><strong>cert-manager</strong> is a Kubernetes controller that automates the full certificate lifecycle. It watches for Ingress resources annotated with an issuer, requests a certificate from a certificate authority, proves you control the domain, stores the certificate in a Kubernetes Secret, and renews it before it expires. Ther eare no cron jobs, manual renewal, or expired-certificate incident at 3 am.</p>
<p>Install it:</p>
<pre><code class="language-bash">helm repo add jetstack https://charts.jetstack.io
helm repo update

helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --version v1.21.2 \
  --set crds.enabled=true
</code></pre>
<p><code>--set crds.enabled=true</code> Installs cert-manager's Custom Resource Definitions: <code>Certificate</code>, <code>Issuer</code>, <code>ClusterIssuer</code>, <code>CertificateRequest</code> and others. These extend the Kubernetes API with new resource types. Without them, cert-manager has nothing to watch for. (If you're following an older tutorial that uses <code>installCRDs=true</code>, that flag was renamed in v1.15.)</p>
<p>Check it's running:</p>
<pre><code class="language-bash">kubectl get pods --namespace cert-manager
</code></pre>
<p>You should see three pods: the controller, the webhook, and cainjector.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/dad07949-4123-4854-861e-5d96e19a4591.png" alt="Output of kubectl get pods showing the cert-manager controller, webhook, and cainjector pods running" style="display: block;" width="1892" height="264" loading="lazy">

<h3 id="heading-create-the-clusterissuer">Create the ClusterIssuer</h3>
<p>An <strong>Issuer</strong> tells cert-manager where to get certificates from. A <strong>ClusterIssuer</strong> is the same thing with cluster-wide scope, which is what we need. A namespaced Issuer would have to be recreated in every single preview namespace.</p>
<p>Create <code>k8s/cluster/letsencrypt-staging.yaml</code>:</p>
<pre><code class="language-yaml">apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-staging
spec:
  acme:
    # Let's Encrypt's staging environment. Certificates from this
    # server are NOT trusted by browsers, but the rate limits are
    # far more generous. Use this while debugging.
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    email: YOUR_EMAIL@example.com
    privateKeySecretRef:
      name: letsencrypt-staging-account-key
    solvers:
      - http01:
          ingress:
            ingressClassName: nginx
</code></pre>
<p>And <code>k8s/cluster/letsencrypt-prod.yaml</code>:</p>
<pre><code class="language-yaml">apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: YOUR_EMAIL@example.com
    privateKeySecretRef:
      name: letsencrypt-prod-account-key
    solvers:
      - http01:
          ingress:
            ingressClassName: nginx
</code></pre>
<p>Apply both:</p>
<pre><code class="language-bash">kubectl apply -f k8s/cluster/letsencrypt-staging.yaml
kubectl apply -f k8s/cluster/letsencrypt-prod.yaml
</code></pre>
<p>Confirm they're ready:</p>
<pre><code class="language-bash">kubectl get clusterissuer
</code></pre>
<p>Both should show <code>READY: True</code>.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/e76271ef-0b0c-471f-b826-d5f476bc33f2.png" alt="Output of kubectl get clusterissuer showing both letsencrypt-staging and letsencrypt-prod with READY status True" style="display: block;" width="1892" height="342" loading="lazy">

<h3 id="heading-why-two-issuers">Why Two Issuers?</h3>
<p>This isn't redundancy. It's how you avoid a frustrating afternoon.</p>
<p>Let's Encrypt enforces strict rate limits on its production environment. The one that matters here is <strong>50 certificates per registered domain per week</strong>. There's also a duplicate-certificate limit of 5 per week for the identical set of hostnames.</p>
<p>While you're setting this up, you'll likely misconfigure something. The Ingress annotation will be wrong, or the HTTP-01 challenge won't route correctly, or DNS won't have propagated. Each failed attempt burns against your quota, and once you hit the limit you're locked out for a week with no appeal.</p>
<p>The staging issuer has far looser limits. Its certificates are signed by an untrusted root, so browsers show a warning, but that warning <em>is itself proof the pipeline works</em>. If you see a certificate warning naming "Let's Encrypt Staging," everything functioned correctly, and the only remaining step is switching issuers.</p>
<p>Use <code>letsencrypt-staging</code> until the flow works end to end, then switch to <code>letsencrypt-prod</code>.</p>
<h3 id="heading-how-the-http-01-challenge-works">How the HTTP-01 Challenge Works</h3>
<p>This is worth understanding, because it's what breaks when things go wrong.</p>
<p>When cert-manager requests a certificate for <code>pr-42.preview.yourdomain.com</code>, Let's Encrypt needs proof you control that hostname. With the HTTP-01 solver, the sequence is:</p>
<ol>
<li><p>Let's Encrypt gives cert-manager a random token.</p>
</li>
<li><p>cert-manager creates a temporary pod, Service, and Ingress rule that serves that token at <code>http://pr-42.preview.yourdomain.com/.well-known/acme-challenge/&lt;token&gt;</code>.</p>
</li>
<li><p>Let's Encrypt makes a real HTTP request to that URL from the public internet.</p>
</li>
<li><p>If the token matches, domain control is proven and the certificate is issued.</p>
</li>
<li><p>cert-manager deletes the temporary resources and stores the certificate in a Secret.</p>
</li>
</ol>
<p>Three things must be true for this to work, and they're the three things to check when it doesn't: DNS must resolve the hostname to your load balancer, port 80 must be reachable from the internet (don't redirect everything to HTTPS at the load balancer level. The challenge is plain HTTP), and the Ingress controller must be routing correctly.</p>
<h3 id="heading-a-note-on-scale">A Note on Scale</h3>
<p>HTTP-01 issues one certificate per hostname, and every preview environment has a unique hostname. That's one certificate per pull request.</p>
<p>Against Let's Encrypt's 50-per-week limit, that's comfortable for a solo project or a small team. An active team opening more than 50 PRs a week would hit the ceiling.</p>
<p>The production answer is to issue a <strong>single wildcard certificate</strong> for <code>*.preview.yourdomain.com</code> and share it across every namespace. Wildcards can't be issued over HTTP-01. They require the <strong>DNS-01</strong> challenge, where cert-manager proves control by creating a TXT record instead of serving a file.</p>
<p>With Cloud DNS, cert-manager can do this automatically using a Google service account. You'd then replicate the resulting Secret into each preview namespace with a tool like <a href="https://github.com/emberstack/kubernetes-reflector">reflector</a>.</p>
<p>That's more moving parts than this handbook needs, but it's the right answer once your PR volume justifies it, and it's worth knowing that limit exists before you hit it.</p>
<h2 id="heading-step-16-add-an-ingress-to-the-base-manifests">Step 16: Add an Ingress to the Base Manifests</h2>
<p>Now we'll give the application a route.</p>
<p>Create <code>k8s/base/ingress.yaml</code>:</p>
<pre><code class="language-yaml">apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: preview-app
  annotations:
    # Tells cert-manager to request a certificate for the hosts
    # listed under spec.tls, using this ClusterIssuer.
    cert-manager.io/cluster-issuer: letsencrypt-staging
    # Redirect HTTP to HTTPS once the certificate exists.
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - preview-host-placeholder
      secretName: preview-app-tls
  rules:
    - host: preview-host-placeholder
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: preview-app
                port:
                  number: 80
</code></pre>
<p>Add it to <code>k8s/base/kustomization.yaml</code>:</p>
<p>You created this file back in Step 8 with two resources. Add the Ingress to it:</p>
<pre><code class="language-yaml">apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
  - deployment.yaml
  - service.yaml
  - ingress.yaml
</code></pre>
<p>Here are the pieces that matter:</p>
<p><code>cert-manager.io/cluster-issuer</code>: this single annotation is what triggers the entire certificate workflow. cert-manager watches for it, reads the hostnames from <code>spec.tls</code>, and does everything else. Note it's set to <code>letsencrypt-staging</code> for now. We'll switch to production once the flow is proven.</p>
<p><code>ingressClassName: nginx</code>: identifies which controller should handle this Ingress. A cluster can run several controllers simultaneously, and this field prevents them from fighting over the same resource. Older tutorials use the <code>kubernetes.io/ingress.class</code> annotation, which is deprecated.</p>
<p><code>secretName: preview-app-tls</code>: where cert-manager stores the issued certificate. It's created automatically in the same namespace as the Ingress, so each preview environment has its own.</p>
<p><code>preview-host-placeholder</code>: deliberately not a valid hostname. It appears twice: once in <code>spec.tls.hosts</code> and once in <code>spec.rules.host</code>, and both get replaced per PR in the next step. Using something that obviously isn't a real domain means that if the patch ever fails, you get an immediate visible error rather than a subtle misroute.</p>
<p><code>pathType: Prefix</code> <strong>with</strong> <code>path: /</code>: matches every path on the host. Preview environments serve the whole application, not a subpath.</p>
<h2 id="heading-step-17-patch-the-hostname-per-pull-request">Step 17: Patch the Hostname Per Pull Request</h2>
<p>Each environment needs its own hostname substituted into two places in the Ingress. Kustomize handles this with a <strong>JSON 6902 patch</strong>. A precise operation that targets an exact path within a resource.</p>
<p>In Step 9, the workflow generated an overlay that set the namespace and image tag. We extend that generated overlay with a patch block. Here's what the complete generated <code>kustomization.yaml</code> looks like for PR 42:</p>
<pre><code class="language-yaml">apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: pr-42

resources:
  - ../../base

images:
  - name: preview-app
    newName: europe-west2-docker.pkg.dev/your-project/pr-preview/preview-app
    newTag: pr-42-a1b2c3d

patches:
  - target:
      kind: Ingress
      name: preview-app
    patch: |-
      - op: replace
        path: /spec/rules/0/host
        value: pr-42.preview.yourdomain.com
      - op: replace
        path: /spec/tls/0/hosts/0
        value: pr-42.preview.yourdomain.com
</code></pre>
<p>The patch syntax reads literally: in the resource matching <code>kind: Ingress, name: preview-app</code>, replace the value at <code>/spec/rules/0/host</code>, and replace the value at <code>/spec/tls/0/hosts/0</code>.</p>
<p>The <code>0</code> indices are array positions. <code>/spec/rules/0</code> is the first (and only) rule. <code>/spec/tls/0/hosts/0</code> is the first hostname in the first TLS block. If you later add a second hostname per environment, you'd add another operation targeting index <code>1</code>.</p>
<p>Why a JSON 6902 patch rather than a strategic merge patch? Because strategic merge on an array of objects is ambiguous. Kubernetes has to guess whether you mean "replace this list" or "merge into an existing entry," and the answer depends on per-field merge keys. For replacing a single value at a known position, an explicit <code>op: replace</code> says exactly what you mean and fails loudly if the path doesn't exist.</p>
<p>The workflow generates this file at runtime, so you never commit a per-PR overlay. We'll write that step in Step 19.</p>
<h2 id="heading-step-18-add-guardrails-with-resourcequota-and-limitrange">Step 18: Add Guardrails with ResourceQuota and LimitRange</h2>
<p>Before we wire up the workflow, let's stop a preview environment from being able to take down the cluster.</p>
<p>Right now nothing prevents a pull request from deploying a manifest requesting 32 CPUs, or scaling to 200 replicas, or creating a dozen <code>LoadBalancer</code> Services. Someone doesn't need bad intent for this to happen. A bad merge, a copied manifest, or a typo in a replica count does it just as effectively.</p>
<p>Two Kubernetes resources solve this, and they work together.</p>
<p>Create <code>k8s/cluster/namespace-guardrails.yaml</code> as a template:</p>
<pre><code class="language-yaml">apiVersion: v1
kind: ResourceQuota
metadata:
  name: preview-quota
spec:
  hard:
    requests.cpu: "1"
    requests.memory: 1Gi
    limits.cpu: "2"
    limits.memory: 2Gi
    pods: "10"
    services: "5"
    services.loadbalancers: "0"
    persistentvolumeclaims: "2"
---
apiVersion: v1
kind: LimitRange
metadata:
  name: preview-limits
spec:
  limits:
    - type: Container
      # Applied to containers that don't specify their own
      defaultRequest:
        cpu: 50m
        memory: 64Mi
      default:
        cpu: 200m
        memory: 128Mi
      # Hard ceiling — a container asking for more is rejected
      max:
        cpu: "1"
        memory: 512Mi
</code></pre>
<h3 id="heading-what-each-one-does">What Each One Does</h3>
<p>A <strong>ResourceQuota</strong> caps the total consumption of an entire namespace. Add up every pod's requests and limits. The sum can't exceed these numbers. A request that would push the namespace over its quota is rejected by the API server at admission time, before anything is scheduled.</p>
<p>The <code>services.loadbalancers: "0"</code> line is worth highlighting. It makes it structurally impossible for a preview environment to provision a Google Cloud load balancer, even if someone commits a manifest with <code>type: LoadBalancer</code>. That's a direct financial guardrail: the most expensive mistake this system could make is now unrepresentable.</p>
<p>A <strong>LimitRange</strong> operates on individual containers rather than the namespace total. It sets defaults for containers that don't specify resources, and a hard maximum that no single container may exceed.</p>
<h3 id="heading-why-they-must-be-deployed-together">Why They Must Be Deployed Together</h3>
<p>Once a ResourceQuota that constrains <code>requests.cpu</code> exists in a namespace, <strong>every container in that namespace must declare resource requests</strong>. A pod without them is rejected outright, because Kubernetes can't verify it fits within the quota if it doesn't know what it's asking for.</p>
<p>That means adding a ResourceQuota on its own will break any manifest that omits resource specs, and most manifests found in the wild do omit them.</p>
<p>The LimitRange fixes this by supplying defaults. A container with no resource spec gets the <code>defaultRequest</code> and <code>default</code> values injected automatically at admission time, which satisfies the quota's requirement.</p>
<p>Deploy one without the other, and you get confusing failures. Deploy both and the system is forgiving of incomplete manifests while still being strictly bounded.</p>
<h3 id="heading-sizing-the-numbers">Sizing the Numbers</h3>
<p>The values above suit a small application like ours. To adjust them, work backwards from your node capacity.</p>
<p>Two <code>e2-standard-2</code> nodes give you 4 vCPU and 16GB total, minus roughly 15% that GKE reserves for system components. Call it 3.4 usable vCPU. With <code>requests.cpu: "1"</code> per namespace, three preview environments could theoretically fill the cluster.</p>
<p>Our application requests only 50m CPU, so in practice you'll fit far more than three. But the quota is a ceiling on what a namespace <em>may</em> request, and you should set it well below "one PR can consume everything."</p>
<p>If you expect ten concurrent environments, size the per-namespace quota at roughly a tenth of usable capacity, or add nodes.</p>
<h2 id="heading-step-19-update-the-deploy-workflow">Step 19: Update the Deploy Workflow</h2>
<p>Here's the complete <code>.github/workflows/preview-deploy.yml</code>, with everything added in this section marked <code># NEW</code>. Replace your Step 9 version with this one.</p>
<pre><code class="language-yaml">name: Deploy PR Preview

on:
  pull_request:
    types: [opened, synchronize, reopened]

concurrency:
  group: preview-${{ github.event.pull_request.number }}
  cancel-in-progress: true

permissions:
  contents: read
  id-token: write
  pull-requests: write

env:
  PROJECT_ID: YOUR_PROJECT_ID
  REGION: europe-west2
  CLUSTER_NAME: pr-preview-cluster
  CLUSTER_ZONE: europe-west2-a
  REPOSITORY: pr-preview
  IMAGE_NAME: preview-app
  # NEW: the base domain for all preview environments
  PREVIEW_DOMAIN: preview.yourdomain.com
  # NEW: switch to letsencrypt-prod once the flow is proven
  CLUSTER_ISSUER: letsencrypt-staging

jobs:
  deploy:
    name: Build and deploy preview
    runs-on: ubuntu-latest

    steps:
      - name: Check out code
        uses: actions/checkout@v4

      - name: Set environment variables
        run: |
          PR_NUMBER=${{ github.event.pull_request.number }}
          SHORT_SHA=$(echo "${{ github.event.pull_request.head.sha }}" | cut -c1-7)

          echo "PR_NUMBER=${PR_NUMBER}"    &gt;&gt; $GITHUB_ENV
          echo "SHORT_SHA=${SHORT_SHA}"    &gt;&gt; $GITHUB_ENV
          echo "NAMESPACE=pr-${PR_NUMBER}" &gt;&gt; $GITHUB_ENV
          echo "IMAGE_TAG=pr-${PR_NUMBER}-${SHORT_SHA}" &gt;&gt; $GITHUB_ENV
          echo "IMAGE_BASE=${{ env.REGION }}-docker.pkg.dev/${{ env.PROJECT_ID }}/${{ env.REPOSITORY }}/${{ env.IMAGE_NAME }}" &gt;&gt; $GITHUB_ENV
          # NEW: the hostname this environment will be reachable at
          echo "PREVIEW_HOST=pr-${PR_NUMBER}.${{ env.PREVIEW_DOMAIN }}" &gt;&gt; $GITHUB_ENV

      - name: Authenticate to Google Cloud
        uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: ${{ secrets.WIF_PROVIDER }}
          service_account: ${{ secrets.WIF_SERVICE_ACCOUNT }}

      - name: Set up gcloud
        uses: google-github-actions/setup-gcloud@v2

      - name: Configure Docker for Artifact Registry
        run: gcloud auth configure-docker ${{ env.REGION }}-docker.pkg.dev --quiet

      - name: Build and push image
        run: |
          docker build \
            --build-arg PR_NUMBER="${PR_NUMBER}" \
            --build-arg GIT_SHA="${SHORT_SHA}" \
            -t "${IMAGE_BASE}:${IMAGE_TAG}" \
            ./app

          docker push "${IMAGE_BASE}:${IMAGE_TAG}"

      - name: Get GKE credentials
        uses: google-github-actions/get-gke-credentials@v2
        with:
          cluster_name: ${{ env.CLUSTER_NAME }}
          location: ${{ env.CLUSTER_ZONE }}

      - name: Create namespace
        run: |
          kubectl create namespace "${NAMESPACE}" \
            --dry-run=client -o yaml | kubectl apply -f -

          # NEW: label it so the reaper knows this namespace is ours
          kubectl label namespace "${NAMESPACE}" \
            app.kubernetes.io/managed-by=pr-preview \
            preview.pr="${PR_NUMBER}" \
            --overwrite

      # NEW: apply the quota and limits before anything deploys
      - name: Apply namespace guardrails
        run: |
          kubectl apply -f k8s/cluster/namespace-guardrails.yaml \
            --namespace="${NAMESPACE}"

      - name: Generate Kustomize overlay
        run: |
          mkdir -p k8s/overlays/"${NAMESPACE}"
          cat &gt; k8s/overlays/"${NAMESPACE}"/kustomization.yaml &lt;&lt;EOF
          apiVersion: kustomize.config.k8s.io/v1beta1
          kind: Kustomization

          namespace: ${NAMESPACE}

          resources:
            - ../../base

          images:
            - name: preview-app
              newName: ${IMAGE_BASE}
              newTag: ${IMAGE_TAG}

          patches:
            - target:
                kind: Ingress
                name: preview-app
              patch: |-
                - op: replace
                  path: /spec/rules/0/host
                  value: ${PREVIEW_HOST}
                - op: replace
                  path: /spec/tls/0/hosts/0
                  value: ${PREVIEW_HOST}
                - op: replace
                  path: /metadata/annotations/cert-manager.io~1cluster-issuer
                  value: ${CLUSTER_ISSUER}
          EOF

          echo "--- Rendered manifest ---"
          kubectl kustomize k8s/overlays/"${NAMESPACE}"

      - name: Deploy
        run: kubectl apply -k k8s/overlays/"${NAMESPACE}"

      - name: Wait for rollout
        run: |
          kubectl rollout status deployment/preview-app \
            --namespace="${NAMESPACE}" \
            --timeout=180s

      # NEW: wait for the TLS certificate to be issued
      - name: Wait for certificate
        continue-on-error: true
        run: |
          echo "Waiting for TLS certificate for ${PREVIEW_HOST}..."
          kubectl wait certificate/preview-app-tls \
            --namespace="${NAMESPACE}" \
            --for=condition=Ready \
            --timeout=180s

      - name: Show deployment details
        run: |
          echo "Preview URL: https://${PREVIEW_HOST}"
          kubectl get pods,svc,ingress,certificate --namespace="${NAMESPACE}"
</code></pre>
<p>There are a few things to understand about the new steps.</p>
<p><strong>The</strong> <code>~1</code> <strong>in the annotation patch path:</strong> this looks like a typo and isn't:</p>
<pre><code class="language-plaintext">path: /metadata/annotations/cert-manager.io~1cluster-issuer
</code></pre>
<p>JSON Pointer paths use <code>/</code> as a separator, so a literal <code>/</code> inside a key has to be escaped. The escape sequence is <code>~1</code>. (And <code>~</code> itself escapes to <code>~0</code>.) Since the annotation key is<code>cert-manager.io/cluster-issuer</code>, the pointer becomes <code>cert-manager.io~1cluster-issuer</code>. Get this wrong, and the patch silently targets a path that doesn't exist.</p>
<p><strong>Namespace labels:</strong> The <code>app.kubernetes.io/managed-by=pr-preview</code> label is what makes the reaper in Step 21 safe. A cleanup job that deletes namespaces matching a name pattern is one bad regex away from deleting something important. A job that only ever touches namespaces carrying a label it applied itself has a much smaller worst case.</p>
<p><strong>Guardrails before deploy:</strong> The ResourceQuota must exist before the application deploys, not after. Applying it afterwards means the first deployment escapes it entirely, and you'd only find out when something exceeded a limit that was never enforced.</p>
<p><code>continue-on-error: true</code> <strong>on the certificate wait:</strong> This is deliberate. Certificate issuance depends on Let's Encrypt, an external service with rate limits and occasional slowness. If issuance is delayed, the environment is still deployed and still works over HTTP.</p>
<p>So failing the entire workflow would be wrong. We note the problem and continue. The PR comment in the next step reflects whether the certificate is actually ready.</p>
<h2 id="heading-step-20-comment-the-url-on-the-pull-request">Step 20: Comment the URL on the Pull Request</h2>
<p>The environment is live. Now it's time to tell people about it.</p>
<p>Add this step to the end of the deploy job:</p>
<pre><code class="language-yaml">      - name: Comment preview URL on PR
        uses: actions/github-script@v7
        with:
          script: |
            const host = process.env.PREVIEW_HOST;
            const sha = process.env.SHORT_SHA;
            const ns = process.env.NAMESPACE;

            // A hidden marker so we can find our own comment later
            const marker = '&lt;!-- pr-preview-environment --&gt;';

            const body = [
              marker,
              '### Preview environment is ready',
              '',
              `**https://${host}**`,
              '',
              `Commit \`${sha}\` · Namespace \`${ns}\``,
              '',
              '&lt;sub&gt;This environment updates on every push and is deleted when the PR closes.&lt;/sub&gt;',
            ].join('\n');

            const { data: comments } = await github.rest.issues.listComments({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
            });

            const existing = comments.find(c =&gt; c.body.includes(marker));

            if (existing) {
              await github.rest.issues.updateComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                comment_id: existing.id,
                body,
              });
            } else {
              await github.rest.issues.createComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: context.issue.number,
                body,
              });
            }
</code></pre>
<p>So why this approach?</p>
<p><code>actions/github-script</code> is maintained by GitHub itself and gives you an authenticated Octokit client with no setup. There are third-party actions that post PR comments in fewer lines, but every third-party action in a workflow with write permissions is a supply chain dependency.</p>
<p>Given the effort we spent in Step 5 removing a long-lived credential, adding an unaudited action that can write to your repository would be an odd trade.</p>
<p><strong>The hidden marker comment</strong> is the mechanism that makes this a <em>sticky</em> comment. <code>&lt;!-- pr-preview-environment --&gt;</code> renders as nothing in GitHub's markdown, but it's present in the comment body. On each run, we list the PR's comments, look for one containing the marker, and update it if found.</p>
<p>Without this, a PR with fifteen commits gets fifteen near-identical bot comments, and the thread becomes unreadable. Reviewers start ignoring bot comments entirely, which defeats the purpose. One comment that stays current is the difference between a useful tool and noise.</p>
<p><code>process.env.PREVIEW_HOST</code>: values written to <code>$GITHUB_ENV</code> in earlier steps are available as environment variables in the script. This is cleaner than interpolating <code>${{ }}</code> expressions directly into JavaScript, which can break in surprising ways if a value contains quotes or backticks.</p>
<p><code>context.issue.number</code> works on <code>pull_request</code> events because GitHub treats pull requests as a specialised kind of issue. It's why we use the <code>issues</code> API to comment on a PR.</p>
<p>The step needs <code>pull-requests: write</code>, which the workflow already declares.</p>
<h2 id="heading-step-21-build-the-reaper">Step 21: Build the Reaper</h2>
<p>Here's the uncomfortable truth about the teardown workflow from Part 1: it will eventually fail to run.</p>
<p>The failure modes are mundane. Someone closes a PR while GitHub Actions is having an incident. A workflow file gets edited on a branch in a way that breaks the teardown job. Someone deletes a branch without closing its PR. A repository is archived with PRs still open. GitHub's event delivery hiccups.</p>
<p>None of these are common. All of them leave a namespace running indefinitely, consuming cluster capacity and (if it happens enough) real money. Cleanup that works 95% of the time is still a leak.</p>
<p>The fix is a <strong>reaper</strong>: a scheduled job that periodically compares what's running against what should be running, and deletes the difference.</p>
<p>Create <code>.github/workflows/preview-reaper.yml</code>:</p>
<pre><code class="language-yaml">name: Reap Orphaned Preview Environments

on:
  schedule:
    # 03:00 UTC daily
    - cron: '0 3 * * *'
  # Allow manual runs from the Actions tab
  workflow_dispatch:

permissions:
  contents: read
  id-token: write
  pull-requests: read

env:
  PROJECT_ID: YOUR_PROJECT_ID
  CLUSTER_NAME: pr-preview-cluster
  CLUSTER_ZONE: europe-west2-a
  # Delete environments older than this even if the PR is still open
  MAX_AGE_DAYS: 7

jobs:
  reap:
    name: Delete orphaned namespaces
    runs-on: ubuntu-latest

    steps:
      - name: Authenticate to Google Cloud
        uses: google-github-actions/auth@v2
        with:
          workload_identity_provider: ${{ secrets.WIF_PROVIDER }}
          service_account: ${{ secrets.WIF_SERVICE_ACCOUNT }}

      - name: Get GKE credentials
        uses: google-github-actions/get-gke-credentials@v2
        with:
          cluster_name: ${{ env.CLUSTER_NAME }}
          location: ${{ env.CLUSTER_ZONE }}

      - name: Reap
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          set -euo pipefail

          echo "Fetching open pull requests..."
          OPEN_PRS=$(gh pr list \
            --repo "${{ github.repository }}" \
            --state open \
            --limit 500 \
            --json number \
            --jq '.[].number')

          echo "Open PRs: ${OPEN_PRS:-none}"
          echo ""

          # Only consider namespaces we created ourselves.
          NAMESPACES=$(kubectl get namespaces \
            -l app.kubernetes.io/managed-by=pr-preview \
            -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.metadata.labels.preview\.pr}{"\t"}{.metadata.creationTimestamp}{"\n"}{end}')

          if [ -z "${NAMESPACES}" ]; then
            echo "No preview namespaces found. Nothing to do."
            exit 0
          fi

          NOW=$(date -u +%s)
          MAX_AGE_SECONDS=$(( MAX_AGE_DAYS * 86400 ))
          DELETED=0

          while IFS=$'\t' read -r NS PR_NUM CREATED; do
            [ -z "${NS}" ] &amp;&amp; continue

            CREATED_EPOCH=$(date -u -d "${CREATED}" +%s)
            AGE=$(( NOW - CREATED_EPOCH ))
            AGE_DAYS=$(( AGE / 86400 ))

            REASON=""

            # Rule 1: the PR is no longer open
            if ! echo "${OPEN_PRS}" | grep -qx "${PR_NUM}"; then
              REASON="PR #${PR_NUM} is not open"
            # Rule 2: the environment has outlived MAX_AGE_DAYS
            elif [ "${AGE}" -gt "${MAX_AGE_SECONDS}" ]; then
              REASON="environment is ${AGE_DAYS} days old (max ${MAX_AGE_DAYS})"
            fi

            if [ -n "${REASON}" ]; then
              echo "DELETING ${NS} — ${REASON}"
              kubectl delete namespace "${NS}" \
                --ignore-not-found=true \
                --wait=false
              DELETED=$(( DELETED + 1 ))
            else
              echo "KEEPING  ${NS} — PR #${PR_NUM} open, ${AGE_DAYS}d old"
            fi
          done &lt;&lt;&lt; "${NAMESPACES}"

          echo ""
          echo "Reaped ${DELETED} namespace(s)."
</code></pre>
<h3 id="heading-where-does-githubtoken-come-from">Where does <code>GITHUB_TOKEN</code> come from?</h3>
<p>Unlike <code>WIF_PROVIDER</code> and <code>WIF_SERVICE_ACCOUNT</code>, which you created in Step 6, <code>GITHUB_TOKEN</code> <strong>isn't something you set up</strong>. You won't find it on the secrets page, and you shouldn't add it there.</p>
<p>GitHub mints a fresh installation token at the start of every workflow run, exposes it as <code>secrets.GITHUB_TOKEN</code>, and revokes it the moment the job finishes. It's scoped to the repository running the workflow and nothing else.</p>
<h3 id="heading-understanding-the-reaper">Understanding the Reaper</h3>
<p>The reaper runs from GitHub Actions, not inside the cluster. A CronJob in Kubernetes would need a GitHub token stored as a cluster Secret to query open PRs. That's a long-lived credential sitting in the cluster, which is exactly what we avoided in Step 5.</p>
<p>A scheduled workflow already has <code>GITHUB_TOKEN</code> (scoped, automatic, short-lived) and already authenticates to GCP through Workload Identity Federation. No new secrets.</p>
<p>The label selector is the safety mechanism. The query is <code>-l app.kubernetes.io/managed-by=pr-preview</code>, not a name pattern like <code>pr-*</code>. This is a deliberate choice: a name-pattern match would happily delete a production namespace someone named <code>pr-routing-service</code>. The reaper can only ever see namespaces that the deploy workflow explicitly labelled, which means the set of things it could possibly delete is the set of things it created.</p>
<p>Be careful when you adapt this. Any cleanup automation should operate on a positive allowlist it controls, never a pattern that could match something it didn't create.</p>
<p>We also have two deletion rules, for two different problems. Rule 1 catches the actual orphan. A namespace whose PR is closed but whose teardown never ran. Rule 2 catches the stale environment: a PR that's been open for three weeks, hasn't been touched in two, and is quietly holding cluster capacity. Seven days is a reasonable default. If someone needs their environment back, they just push a commit, and it redeploys in a couple of minutes.</p>
<p><code>set -euo pipefail</code>: <code>-e</code> exits on any command failure, <code>-u</code> errors on undefined variables, and <code>-o pipefail</code> makes a pipeline fail if <em>any</em> stage fails rather than only the last. In a script whose job is deleting things, silent failure is the worst outcome. If something goes wrong, stop immediately.</p>
<p><code>grep -qx</code>: the <code>-x</code> flag requires the whole line to match. Without it, PR <code>4</code> would match against open PR <code>42</code> and the reaper would spare an orphaned namespace forever. It's a small flag, but a real bug.</p>
<p><code>workflow_dispatch</code> lets you run the reaper manually from the Actions tab. Do that the first few times and read the output before trusting the schedule. The log prints <code>KEEPING</code> or <code>DELETING</code> with a reason for every namespace, so you can verify the logic matches your expectations before it runs unattended.</p>
<h2 id="heading-step-22-test-the-whole-thing">Step 22: Test the Whole Thing</h2>
<p>Commit everything and push:</p>
<pre><code class="language-bash">git add .
git commit -m "Add Ingress, TLS, PR comments, guardrails, and reaper"
git push
</code></pre>
<p>Create a branch, make a visible change, and open a pull request:</p>
<pre><code class="language-bash">git checkout -b test-preview-urls
# edit app/main.go — change the greeting text
git add .
git commit -m "Test preview URLs"
git push -u origin test-preview-urls
</code></pre>
<p>Open the PR and watch the Actions tab.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/5c13299f-c72c-4073-8ab0-2f552749cee5.png" alt="The deploy workflow running with the new certificate and comment step" style="display: block;" width="2366" height="1434" loading="lazy">

<p>When it finishes, the bot comment should appear with your URL. Open it.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/652f2033-7672-4f32-9a53-e2837c97bab2.png" alt="The bot comment showing the new URL" style="display: block;" width="2366" height="1434" loading="lazy">

<p>Because you're still on the staging issuer, your browser will show a certificate warning. Something like "Your connection is not private," with an issuer of "Let's Encrypt Staging."</p>
<p><strong>This is the success condition.</strong> It means DNS resolved, the load balancer routed, the Ingress matched the hostname, the HTTP-01 challenge completed, and a certificate was issued. Everything worked. The certificate simply comes from an untrusted test authority.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/4e0e252f-66e4-47fa-a0cf-31a0c491a73a.png" alt="Browser security warning for the preview environment URL, showing the certificate was issued by Let's Encrypt Staging rather than a trusted authority" style="display: block;" width="2366" height="1434" loading="lazy">

<p>Click Advanced, pass through the warning, and confirm the application responds with the right PR number and namespace.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/094f0273-1a55-4d84-ac42-b3dca2b8ce58.png" alt="The preview environment loading in the browser, showing the application's output with the correct PR number, commit SHA, and namespace" style="display: block;" width="2366" height="954" loading="lazy">

<p>Check the certificate from the command line:</p>
<pre><code class="language-bash">kubectl get certificate --namespace=pr-2 
#Ensure you use your own pr-number
</code></pre>
<p>You want <code>READY: True</code>. If it's <code>False</code>, inspect what's happening:</p>
<pre><code class="language-bash">kubectl describe certificate preview-app-tls --namespace=pr-2
kubectl get challenges --all-namespaces
</code></pre>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/d27a623d-f1fc-49bd-a1eb-69d277a17631.png" alt="Checking the certificate from the command line" style="display: block;" width="2366" height="1208" loading="lazy">

<p>A pending challenge that never resolves almost always means DNS or port 80 reachability. Confirm with:</p>
<pre><code class="language-bash">curl -I http://pr-2.preview.yourdomain.com/.well-known/acme-challenge/test
</code></pre>
<p>You want any HTTP response from NGINX. A 404 is fine, as it proves that the routing works. A connection timeout means the request isn't reaching your cluster.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/5b539f11-bc2b-46e8-853d-7f8b9d783b8e.png" alt="Confirming DNS reachability" style="display: block;" width="2366" height="358" loading="lazy">

<h3 id="heading-switch-to-production-certificates">Switch to Production Certificates</h3>
<p>Once the staging flow works end to end, change one line in the workflow's <code>env:</code> block:</p>
<pre><code class="language-yaml">  CLUSTER_ISSUER: letsencrypt-prod
</code></pre>
<p>Make this change <strong>on your existing PR branch</strong> and push it. You don't need to close the pull request or merge to <code>main</code> first. You can also change the message in your main.go file to confirm everything works.</p>
<p>Push a new commit to the PR. The environment redeploys, cert-manager requests a real certificate, and this time the browser shows a padlock.</p>
<p>Open the URL in a <strong>private browsing window</strong> to check. Your browser cached an exception for the staging certificate against that hostname, and a normal tab may show a trusted-looking page that's really just a remembered override and still shows <code>not secure</code>.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/54b5979c-f3d9-4dca-a63d-970e4e66e219.png" alt="The preview environment loading over HTTPS with a valid certificate" style="display: block;" width="1046" height="758" loading="lazy">

<h3 id="heading-verify-the-guardrails">Verify the Guardrails</h3>
<p>Confirm the quota is active:</p>
<pre><code class="language-bash">kubectl describe resourcequota preview-quota --namespace=pr-2
</code></pre>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/9d50f2e6-9802-424e-8be7-7955ba8dcd92.png" alt="Output of kubectl describe resourcequota showing the preview-quota in namespace pr-1 with used and hard limits listed for CPU, memory, pods, services, and load balancers" style="display: block;" width="1820" height="532" loading="lazy">

<p>You'll see used versus hard limits for each resource. Then try to break it:</p>
<pre><code class="language-bash">kubectl scale deployment/preview-app --replicas=50 --namespace=pr-2
kubectl get events --namespace=pr-2 | grep -i quota
</code></pre>
<p>The deployment will scale partway and then stop, with events explaining that it exceeded the quota. That's the guardrail doing its job: the namespace is bounded, and the rest of the cluster is unaffected.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/13872121-d7a9-49e5-b85f-34a629afc77a.png" alt="Terminal output showing the deployment scaled only partway to 50 replicas, with Kubernetes events reporting that the request exceeded the namespace quota" style="display: block;" width="2728" height="854" loading="lazy">

<h3 id="heading-verify-teardown-and-the-reaper">Verify Teardown and the Reaper</h3>
<p>Close the pull request. The teardown workflow fires and the namespace goes to <code>Terminating</code>.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/336470b2-df0d-4f14-bab3-6f17f38ad4f3.png" alt="Github Actions teardown workflow job completed" style="display: block;" width="2342" height="1434" loading="lazy">

<p>Then test the reaper on a namespace it <em>shouldn't</em> touch. Create one manually without the label:</p>
<pre><code class="language-bash">kubectl create namespace pr-9999
</code></pre>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/ac2c98c2-f8fc-4cbb-b5e9-8cae679fd4cf.png" alt="Terminal showing kubectl create namespace pr-9999, creating a namespace without the pr-preview management label" style="display: block;" width="2342" height="140" loading="lazy">

<p>Run the reaper manually from the Actions tab.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/4941adde-9be6-4870-8742-47920ffa8f97.png" alt="GitHub Actions interface showing the Reap Orphaned Preview Environments workflow with the Run workflow button available through workflow_dispatch" style="display: block;" width="2402" height="1196" loading="lazy">

<p>It should ignore <code>pr-9999</code> entirely, because that namespace carries no <code>app.kubernetes.io/managed-by=pr-preview</code> label. The log won't even mention it.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f97fb446ea7602886a16070/a16298d1-c63a-45f3-b117-a35ba79fc9e9.png" alt="GitHub Actions log for the reaper showing it found no preview namespaces to act on, having ignored the unlabelled pr-9999 namespace entirely" style="display: block;" width="2402" height="1196" loading="lazy">

<p>Clean it up yourself:</p>
<pre><code class="language-bash">kubectl delete namespace pr-9999
</code></pre>
<p>That test matters more than it looks. You've just verified that your automated deletion job can't touch things it didn't create.</p>
<h2 id="heading-what-this-costs">What This Costs</h2>
<p>We should be concrete about this, since cost control is half the argument for this pattern.</p>
<p>Running continuously in <code>europe-west2</code>, here are the approximate monthly figures:</p>
<table>
<thead>
<tr>
<th>Component</th>
<th>Approximate cost</th>
</tr>
</thead>
<tbody><tr>
<td>GKE control plane</td>
<td>~$74/month (one zonal cluster, free tier covers one cluster on some accounts)</td>
</tr>
<tr>
<td>2 × <code>e2-standard-2</code> nodes</td>
<td>~$97/month</td>
</tr>
<tr>
<td>Regional load balancer</td>
<td>~$18/month + data processing</td>
</tr>
<tr>
<td>Static IP (in use)</td>
<td>Free while attached</td>
</tr>
<tr>
<td>Artifact Registry storage</td>
<td>~$0.10/GB/month</td>
</tr>
<tr>
<td>Let's Encrypt certificates</td>
<td>Free</td>
</tr>
<tr>
<td>GitHub Actions (public repo)</td>
<td>Free</td>
</tr>
</tbody></table>
<p>Call it roughly $190/month for the always-on infrastructure, regardless of how many preview environments you run.</p>
<p>The number that matters is what <em>doesn't</em> scale with PR count. One load balancer serves every environment. One DNS record covers every hostname. Certificates are free. The marginal cost of the eleventh preview environment is only the node capacity its pods consume, a few pence a day for an application this size.</p>
<p>Compare that with the naïve approach of a <code>LoadBalancer</code> Service per environment: ten open PRs would add roughly $180/month in load balancers alone, and that's before anyone forgets to clean one up. The <code>services.loadbalancers: "0"</code> line in the ResourceQuota exists specifically to make that mistake impossible.</p>
<p>There are two ways to cut the standing cost for a personal project. Use <strong>spot nodes</strong>, add <code>spot = true</code> to the <code>node_config</code> block in Terraform for roughly a 60–70% discount on node hours. Preview environments are the ideal spot workload: if a node is reclaimed, pods reschedule, and the worst case is a preview environment briefly restarting. Or scale the node pool to zero overnight with a scheduled workflow, since nobody reviews PRs at 3 am.</p>
<h2 id="heading-cleanup">Cleanup</h2>
<p>When you're finished:</p>
<pre><code class="language-bash"># Delete every preview namespace
kubectl delete namespaces -l app.kubernetes.io/managed-by=pr-preview

# Remove the shared infrastructure
helm uninstall cert-manager --namespace cert-manager
helm uninstall ingress-nginx --namespace ingress-nginx
kubectl delete namespace cert-manager ingress-nginx
</code></pre>
<p>Uninstall the Helm releases <em>before</em> running <code>terraform destroy</code>. The Ingress controller's Service owns a Google Cloud load balancer that Terraform doesn't know about, because Kubernetes created it rather than Terraform. Destroying the cluster first can orphan that load balancer, leaving it billing quietly in a project with nothing else in it.</p>
<h3 id="heading-if-you-plan-to-rebuild-this-later">If You Plan to Rebuild This Later</h3>
<p><strong>Don't run a full</strong> <code>terraform destroy</code><strong>.</strong> Tear down only the expensive parts:</p>
<pre><code class="language-bash">cd terraform 
terraform destroy 
-var="project_id=YOUR_PROJECT_ID" 
-var="github_repo=YOUR_USERNAME/pr-preview-envs"
</code></pre>
<p>Here's why. When you delete a Workload Identity Pool, Google doesn't remove it immediately. It marks it <code>DELETED</code> and reserves the ID for 30 days. Terraform forgets about it, but Google hasn't. Recreating the stack within that window fails with:</p>
<pre><code class="language-plaintext">Error: Error creating WorkloadIdentityPool: googleapi: Error 409: Requested entity already exists
</code></pre>
<p>Almost all of your cost is the cluster and its nodes. The identity pool, provider, service account, IAM bindings, static IP, and Artifact Registry repository cost nothing or pennies to leave in place. Rebuilding later is then just <code>terraform apply</code>, and your <code>WIF_PROVIDER</code> and <code>WIF_SERVICE_ACCOUNT</code> secrets in GitHub stay valid. No need to update them.</p>
<p>If you want to keep the cluster but stop paying for idle nodes, scale the node pool to zero instead:</p>
<pre><code class="language-bash">gcloud container clusters resize pr-preview-cluster
--node-pool pr-preview-cluster-pool
--num-nodes 0
--zone europe-west2-a
</code></pre>
<p>You still pay for the GKE control plane, so this reduces cost rather than eliminating it.</p>
<p>If you're done for good:</p>
<pre><code class="language-bash">cd terraform
terraform destroy
-var="project_id=YOUR_PROJECT_ID"
-var="github_repo=YOUR_USERNAME/pr-preview-envs" 
</code></pre>
<p>Then confirm nothing was left behind:</p>
<pre><code class="language-bash">gcloud compute forwarding-rules list
gcloud compute addresses list
</code></pre>
<p>Both should be empty, or contain only resources belonging to other projects of yours. Don't forget to remove the wildcard DNS record too.</p>
<h2 id="heading-conclusion">Conclusion</h2>
<p>You've built something that most engineering teams either don't have or pay a vendor for.</p>
<p>You wrote a Go application that reports its own build metadata, injected at compile time through linker flags, so a running environment can always tell you exactly which commit it came from. You wrapped it in a multi-stage Dockerfile that produces a small, statically linked, non-root image</p>
<p>You provisioned a GKE cluster and an Artifact Registry repository with Terraform, which means the whole environment is reproducible and destroyable with a single command. You set up Workload Identity Federation so GitHub Actions authenticates to Google Cloud with short-lived OIDC tokens instead of a long-lived service account key, scoped to exactly one repository by an attribute condition.</p>
<p>You wrote base Kubernetes manifests once and used Kustomize overlays, generated at runtime, to deploy the same application into a different namespace with a different image tag and a different hostname for every pull request. You put a single shared Ingress controller in front of every environment and gave it a stable static IP, so one load balancer serves any number of previews. You pointed one wildcard DNS record at it, which means a new environment needs no DNS work at all: routing happens on the <code>Host</code> header inside the cluster. You added cert-manager so every environment gets a valid, auto-renewing TLS certificate, and made the pipeline announce itself with a sticky PR comment that updates in place.</p>
<p>You bounded each namespace with a ResourceQuota and LimitRange, including one line that makes the most expensive possible mistake structurally impossible. And you built a reaper that catches what the happy path misses, operating only on namespaces it can prove it created.</p>
<p>The result is that an isolated, production-shaped, publicly reachable environment is the <strong>default</strong> for every change, not something a developer has to request, claim in a Slack channel, or remember to clean up.</p>
<h3 id="heading-where-to-go-from-here">Where to Go From Here</h3>
<p>There are a few directions you can explore. Here they are, roughly in order of how much they'd improve a real team's experience:</p>
<ol>
<li><p><strong>Seed data for each environment.</strong> The biggest limitation of what we built is that the application is stateless. Real applications need a database. The common patterns are a per-namespace ephemeral database seeded from a sanitised snapshot, or a shared database with per-environment schema isolation. This is the single hardest problem in preview environments and where most of the remaining engineering effort goes.</p>
</li>
<li><p><strong>Run your test suite against the preview.</strong> Once the environment has a real URL, end-to-end tests can run against it in CI, a far stronger signal than tests against mocks.</p>
</li>
<li><p><strong>Wildcard certificates via DNS-01.</strong> As covered in Step 15, this removes the Let's Encrypt rate limit ceiling once your PR volume approaches it.</p>
</li>
<li><p><strong>Move to GitOps.</strong> Rather than the workflow running <code>kubectl apply</code> directly, have it commit the rendered manifests to a repository that Argo CD or Flux reconciles. The cluster's state then has a git history, and your CI pipeline no longer needs cluster write access at all.</p>
</li>
<li><p><strong>Preview environment metrics.</strong> Hook the namespaces into the cost visibility tooling you'd use elsewhere, and you can answer "what do preview environments actually cost us per month" with a number rather than a shrug.</p>
</li>
</ol>
<h2 id="heading-project-file-structure">Project File Structure</h2>
<pre><code class="language-plaintext">pr-preview-envs/
├── app/
│   ├── main.go                      — Go HTTP server reporting build metadata
│   ├── go.mod                       — Go module definition
│   └── Dockerfile                   — Multi-stage build with ldflags injection
├── terraform/
│   ├── main.tf                      — GKE, Artifact Registry, WIF, static IP
│   ├── variables.tf                 — Input variables
│   └── outputs.tf                   — Cluster, WIF, and ingress IP values
├── k8s/
│   ├── base/
│   │   ├── deployment.yaml          — Deployment with probes and Downward API
│   │   ├── service.yaml             — ClusterIP Service
│   │   ├── ingress.yaml             — Ingress with cert-manager annotation
│   │   └── kustomization.yaml       — Base Kustomize config
│   └── cluster/
│       ├── letsencrypt-staging.yaml — Staging ClusterIssuer
│       ├── letsencrypt-prod.yaml    — Production ClusterIssuer
│       └── namespace-guardrails.yaml — ResourceQuota and LimitRange
└── .github/
    └── workflows/
        ├── preview-deploy.yml       — Build, deploy, certificate, PR comment
        ├── preview-teardown.yml     — Delete namespace on PR close
        └── preview-reaper.yml       — Scheduled orphan cleanup
</code></pre>
<p>All source files for this tutorial are available in the companion GitHub repository: <a href="https://github.com/Amiynarh/pr-preview-envs"><code>https://github.com/Amiynarh/pr-preview-envs</code></a>.</p>
 ]]>
                </content:encoded>
            </item>
        
            <item>
                <title>
                    <![CDATA[ How to Build an AI Support System That Automatically Routes Bugs to GitHub with Next.js and Jev ]]>
                </title>
                <description>
                    <![CDATA[ Every website gets feedback, and most of it ends up somewhere awkward. A visitor finds a broken button and emails you. Someone else leaves a comment on social media about a page that won't load on the ]]>
                </description>
                <link>https://www.freecodecamp.org/news/build-an-ai-support-system-that-automatically-routes-bugs-to-github/</link>
                <guid isPermaLink="false">6abfc515257f8ade20662b79</guid>
                
                    <category>
                        <![CDATA[ AI ]]>
                    </category>
                
                    <category>
                        <![CDATA[ Next.js ]]>
                    </category>
                
                    <category>
                        <![CDATA[ GitHub ]]>
                    </category>
                
                    <category>
                        <![CDATA[ React ]]>
                    </category>
                
                    <category>
                        <![CDATA[ TypeScript ]]>
                    </category>
                
                    <category>
                        <![CDATA[ Open Source ]]>
                    </category>
                
                    <category>
                        <![CDATA[ Web Development ]]>
                    </category>
                
                <dc:creator>
                    <![CDATA[ Andrew Baisden ]]>
                </dc:creator>
                <pubDate>Fri, 02 Oct 2026 14:52:05 +0000</pubDate>
                <media:content url="https://cdn.hashnode.com/uploads/covers/5e1e335a7a1d3fcc59028c64/13431986-02ba-4353-8fa7-793542e0e03f.png" medium="image" />
                <content:encoded>
                    <![CDATA[ <p>Every website gets feedback, and most of it ends up somewhere awkward. A visitor finds a broken button and emails you. Someone else leaves a comment on social media about a page that won't load on their phone. A third person fills in your contact form with a feature idea, and it sits in your inbox between a newsletter and a receipt.</p>
<p>When you finally sit down to fix things, the bug reports are scattered across three places. Half of them are missing details, and the ones that do make it into GitHub were copied there by hand, sometimes with the visitor's email address still pasted into a public issue.</p>
<p>I wanted something better for my own projects, so I built it. <strong>IssueRelay</strong> gives any React website a small support widget where visitors can ask a question, report a bug, or suggest a feature. Every report is saved to your own database first. Then an AI model called Jev classifies it, a set of plain rules in code decides where it goes, and you review it in a private dashboard.</p>
<p>When you confirm that a report really is a bug, IssueRelay creates one clean GitHub issue for it, with the visitor's private details removed. When you later close that issue on GitHub, the support ticket closes too.</p>
<p>In this tutorial, you'll learn how the whole system works, from the widget in the browser to the webhook that keeps GitHub and the dashboard in sync. You'll also see how to deploy your own copy in about 15 minutes.</p>
<p>IssueRelay is open source on GitHub at <a href="https://github.com/andrewbaisden/issuerelay">andrewbaisden/issuerelay</a>, the widget is published on npm as <a href="https://www.npmjs.com/package/@issuerelay/widget"><code>@issuerelay/widget</code></a>, and it's running in production on my portfolio website right now.</p>
<p>I won't paste the whole codebase into this article. The repository has every file, and the setup guide walks through installation step by step. Instead, I'll show you the small pieces of code that carry the important ideas, explain what each one does, and share what I learned while building, testing, and deploying it.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f46a01aa639932bd830f982/41588a15-244b-496e-b48e-a284a26d2526.png" alt="The IssueRelay support widget open on a website, showing the Ask a question, Report a bug, and Suggest a feature options" style="display: block;" width="1440" height="900" loading="lazy">

<h2 id="heading-table-of-contents">Table of Contents</h2>
<ul>
<li><p><a href="#heading-table-of-contents">Table of Contents</a></p>
</li>
<li><p><a href="#heading-prerequisites">Prerequisites</a></p>
</li>
<li><p><a href="#heading-how-an-ai-support-system-can-help-any-website">How an AI Support System Can Help Any Website</a></p>
</li>
<li><p><a href="#heading-what-well-build">What We'll Build</a></p>
</li>
<li><p><a href="#heading-what-is-jev">What Is Jev?</a></p>
</li>
<li><p><a href="#heading-the-tech-stack">The Tech Stack</a></p>
</li>
<li><p><a href="#heading-how-a-report-travels-through-the-system">How a Report Travels Through the System</a></p>
</li>
<li><p><a href="#heading-how-to-deploy-your-own-issuerelay">How to Deploy Your Own IssueRelay</a></p>
</li>
<li><p><a href="#heading-running-it-on-a-real-website">Running It on a Real Website</a></p>
</li>
<li><p><a href="#heading-testing-it-end-to-end-and-what-i-learned">Testing It End to End (and What I Learned)</a></p>
</li>
<li><p><a href="#heading-how-it-was-built-phases-and-ai-assisted-development">How It Was Built: Phases and AI Assisted Development</a></p>
</li>
<li><p><a href="#heading-publishing-the-widget-to-npm">Publishing the Widget to npm</a></p>
</li>
<li><p><a href="#heading-what-is-next">What Is Next</a></p>
</li>
<li><p><a href="#heading-conclusion">Conclusion</a></p>
</li>
</ul>
<h2 id="heading-prerequisites">Prerequisites</h2>
<p>To follow along and deploy your own copy, you should have:</p>
<ul>
<li><p><strong>Working knowledge of React, Next.js, and TypeScript:</strong> the platform uses the Next.js App Router, and the widget is a React component.</p>
</li>
<li><p><strong>Node.js 24 and pnpm:</strong> installed if you want to run the project locally or use the command that creates your GitHub App.</p>
</li>
<li><p><strong>A GitHub account:</strong> plus the repository for the website or app where you want to install the widget. Confirmed bugs become issues there.</p>
</li>
<li><p><strong>A Vercel account:</strong> The free Hobby plan is enough. You'll add a Neon PostgreSQL database through Vercel's marketplace, and Neon also has a free plan.</p>
</li>
<li><p><strong>A TypeSafe account:</strong> at <a href="https://typesafe.ai">typesafe.ai</a> for Jev, the AI model that triages reports. You need an API key from the <a href="https://console.typesafe.ai/keys">TypeSafe console</a> before any report can become a GitHub issue.</p>
</li>
<li><p><strong>A React website:</strong> where you can add a component. A Next.js site is the easiest place to start.</p>
</li>
<li><p><strong>Optional: a Resend account:</strong> if you want account emails such as password resets.</p>
</li>
</ul>
<p>You don't need to be an AI expert to follow along. Jev is used through a small, typed SDK, and most of the interesting work is ordinary web engineering: databases, validation, authentication, and webhooks.</p>
<h2 id="heading-how-an-ai-support-system-can-help-any-website">How an AI Support System Can Help Any Website</h2>
<p>A support system sounds like something only big companies need, but the problem it solves shows up on almost every website:</p>
<ul>
<li><p><strong>Portfolio sites</strong> get messages from recruiters, questions about projects, and reports about pages that break on a particular browser.</p>
</li>
<li><p><strong>SaaS products</strong> get bug reports mixed with billing questions and feature requests, and each one needs a different person or process.</p>
</li>
<li><p><strong>Documentation sites</strong> get "this example doesn't work" reports that are really bugs in the product.</p>
</li>
<li><p><strong>Open source projects</strong> get users who won't open a GitHub issue themselves but will happily click a button on the website.</p>
</li>
<li><p><strong>Client sites</strong> you built for someone else get feedback that the client forwards to you days later with no details.</p>
</li>
</ul>
<p>A good system gives you one place where every report arrives, keeps each report safe even when other services fail, and sorts reports so you spend your time on the ones that matter.</p>
<p>The AI part helps with the sorting, but it should never be in charge. A model can be confidently wrong, and a public GitHub issue isn't something you want to create on a guess. So IssueRelay follows one simple rule throughout: AI recommends, a human confirms, and code enforces the rules.</p>
<h2 id="heading-what-well-build">What We'll Build</h2>
<p>Here's the journey of a single report through IssueRelay:</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f46a01aa639932bd830f982/69c55783-997b-4f80-876b-22721315e898.png" alt="Here is the journey of a single report through IssueRelay" style="display: block;" width="1672" height="941" loading="lazy">

<p>A visitor opens the widget on your site and picks a topic:</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f46a01aa639932bd830f982/2a45c808-676c-4a10-8b55-93a0e393e262.png" alt="The widget open on a demo site with its three topics: Ask a question, Report a bug, and Suggest a feature" style="display: block;" width="2560" height="1720" loading="lazy">

<p>They describe the problem and can optionally leave a name and email so you can follow up:</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f46a01aa639932bd830f982/cdcf5b75-44da-47f5-9eeb-21583dcfae0c.png" alt="The Report a bug form in the widget with a message, a name, and an email address filled in" style="display: block;" width="2560" height="1720" loading="lazy">

<p>The widget sends the report to your IssueRelay platform, which saves it and replies with a support reference the visitor can quote later:</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f46a01aa639932bd830f982/39e72c56-5dc2-4c76-bc86-fc9d65e71bc4.png" alt="The widget confirming Message received with the support reference SUP-9" style="display: block;" width="2560" height="1720" loading="lazy">

<p>From there, the report becomes a ticket in your dashboard. Jev classifies it, you review it, and if it is a real bug, one click creates a GitHub issue in your repository.</p>
<p>Here's the full feature list:</p>
<ul>
<li><p><strong>An embeddable widget:</strong> Built as a React component inside a Shadow DOM, so it needs no CSS setup and never clashes with your site's styles. It works in the Next.js App Router and under a strict Content Security Policy.</p>
</li>
<li><p><strong>Durable intake:</strong> Every report is stored in PostgreSQL before anything else runs, with protection against duplicates, per project rate limits, and a list of allowed site addresses.</p>
</li>
<li><p><strong>Bounded AI triage:</strong> Jev recommends a type and severity from the message alone.</p>
</li>
<li><p><strong>A private dashboard:</strong> With filters, classification history, and human review decisions that are stored separately from the AI's output.</p>
</li>
<li><p><strong>Careful GitHub escalation:</strong> Issues are created by a GitHub App only after an owner confirms a preview, and contact details never leave IssueRelay.</p>
</li>
<li><p><strong>Two way sync:</strong> Closing or reopening the issue on GitHub updates the ticket through signed webhooks.</p>
</li>
<li><p><strong>Self hosting:</strong> A Deploy button, a first run setup page, and a settings page make it possible to run your own copy without touching the database.</p>
</li>
</ul>
<h2 id="heading-what-is-jev">What Is Jev?</h2>
<p>Jev is a model from <a href="https://typesafe.ai">TypeSafe</a> that's built for what TypeSafe calls "System One" tasks: quick, bounded judgments as opposed to long, open ended writing.</p>
<p>Instead of asking a model to write a paragraph and then trying to parse it, you give Jev some state and a set of questions, and each question has a fixed list of possible answers. Jev picks an answer for each question and returns the probability it assigned to every option.</p>
<p>That shape is exactly what support triage needs. A ticket is a bug, a question, a feature request, a billing problem, or spam. It's low, medium, high, or critical. There's no text for the model to invent, no prompt injection that can make it write an issue title, and no free text to clean up afterwards. The output is a label and a number, and your code can check both.</p>
<p>It's also cheap and fast. At the time of writing, TypeSafe lists Jev at $42 per billion input tokens, and a support message is a few dozen tokens. The IssueRelay integration sends Jev only the visitor's message and the topic they picked. It never sends names, email addresses, ticket IDs, or anything else that identifies a person.</p>
<h2 id="heading-the-tech-stack">The Tech Stack</h2>
<p>IssueRelay is built with a modern TypeScript stack, and it's the same stack I use for my own projects. If you've read <a href="https://www.freecodecamp.org/news/author/andrewbaisden/">my other articles</a>, a lot of it will look familiar:</p>
<ul>
<li><p><strong>Next.js 16 (App Router) and React 19</strong> for the platform and the dashboard</p>
</li>
<li><p><strong>Strict TypeScript</strong> everywhere, with <strong>Zod</strong> checking every input that crosses a trust boundary: public API requests, environment variables, AI output, and GitHub webhook payloads</p>
</li>
<li><p><strong>PostgreSQL with Drizzle ORM</strong> and reviewed SQL migrations</p>
</li>
<li><p><strong>Better Auth</strong> for dashboard accounts</p>
</li>
<li><p><strong>The official TypeSafe SDK</strong> for Jev, and <strong>Octokit</strong> for the GitHub App</p>
</li>
<li><p><strong>Vitest, React Testing Library, and Playwright</strong> for tests, and <strong>Biome</strong> for linting and formatting</p>
</li>
<li><p><strong>pnpm workspaces</strong> to hold everything in one monorepo</p>
</li>
<li><p><strong>Vercel, Neon, and Resend</strong> in production</p>
</li>
</ul>
<p>The monorepo is split into small packages, each with a strict job:</p>
<table>
<thead>
<tr>
<th>Package</th>
<th>Responsibility</th>
</tr>
</thead>
<tbody><tr>
<td><code>apps/web</code></td>
<td>The platform: the public ticket API, the dashboard, setup, and the GitHub webhook</td>
</tr>
<tr>
<td><code>packages/widget</code></td>
<td>The browser widget published to npm. It never imports server code.</td>
</tr>
<tr>
<td><code>packages/support-contracts</code></td>
<td>The request and response shapes shared by the widget and the API</td>
</tr>
<tr>
<td><code>packages/db</code></td>
<td>The Drizzle schema, migrations, and every database query</td>
</tr>
<tr>
<td><code>packages/ai</code></td>
<td>The Jev adapter, the triage service, and the routing policy</td>
</tr>
<tr>
<td><code>packages/github</code></td>
<td>The GitHub App client, issue drafts, the privacy gate, and webhook handling</td>
</tr>
<tr>
<td><code>packages/auth</code></td>
<td>Better Auth setup, sessions, and workspace membership checks</td>
</tr>
</tbody></table>
<p>The boundaries matter more than they might look like they do. React components never talk to GitHub, Jev, or the database directly. Browser code never contains a secret. The AI package can't import the database.</p>
<p>Keeping those lines strict made the system much easier to test and to reason about, and it's the reason the widget can be published to npm without dragging any server code along with it.</p>
<h2 id="heading-how-a-report-travels-through-the-system">How a Report Travels Through the System</h2>
<p>Let's follow one report from the visitor's browser all the way to a closed GitHub issue.</p>
<h3 id="heading-step-1-the-widget">Step 1: The Widget</h3>
<p>The widget is a normal React component that you install from npm:</p>
<pre><code class="language-shell">npm install @issuerelay/widget
</code></pre>
<p>Then you render it once, for example from a client component in your root layout:</p>
<pre><code class="language-typescript">"use client";

import {
  HttpSupportSubmissionClient,
  SupportWidget,
} from "@issuerelay/widget";

const submissionClient = new HttpSupportSubmissionClient({
  apiBaseUrl: "https://your-issuerelay.vercel.app",
});

export function Support() {
  return (
    &lt;SupportWidget
      projectKey="pk_your_project_key"
      submissionClient={submissionClient}
      theme="system"
      position="bottom-right"
    /&gt;
  );
}
</code></pre>
<p><code>HttpSupportSubmissionClient</code> is the part that talks to your platform. It posts each report to your IssueRelay API without cookies or credentials, and it gives every report a submission ID so that a retry after a network error doesn't create a second ticket.</p>
<p><code>SupportWidget</code> is the button and panel your visitors see. The <code>projectKey</code> tells the platform which project the report belongs to. It's public identification, not a password, so it's safe to put in your site's code. The real protection is on the server, which only accepts reports from the site addresses you list for that project.</p>
<p>The <code>"use client"</code> line is there because the submission client is created in the browser. In the Next.js App Router, you wrap the widget in your own small client component like this and render that component from your layout.</p>
<p>Under the hood, the widget renders inside a Shadow DOM with its own bundled styles, so your site doesn't need Tailwind or a CSS import, and your styles can't accidentally restyle it.</p>
<p>You don't have to write this code by hand, either. IssueRelay's project settings page shows this exact snippet with your platform address and project key already filled in.</p>
<h3 id="heading-step-2-save-first-think-later">Step 2: Save First, Think Later</h3>
<p>When the report reaches the API, the first thing IssueRelay does is save it. Not classify it, not send it anywhere, just store it in PostgreSQL inside a transaction.</p>
<p>This is the most important design decision in the whole system. AI providers have outages. GitHub has outages. If the platform called Jev before saving the report and Jev timed out, the visitor's message would be lost, and they would never know.</p>
<p>So the rule is simple: <strong>a report is accepted only after it's safely stored, and a failure in any later step can never erase it.</strong> If Jev is down, the ticket waits in the dashboard until you run triage again.</p>
<p>Before saving, the API checks a few things:</p>
<ul>
<li><p>The request body matches the shared Zod contract, so bad input is rejected with a clear error.</p>
</li>
<li><p>The project key exists, and the request's origin is one of the project's allowed site addresses.</p>
</li>
<li><p>The project is under its rate limit.</p>
</li>
<li><p>The submission ID hasn't been used before. A repeated submission returns the original ticket reference instead of creating a duplicate.</p>
</li>
</ul>
<h3 id="heading-step-3-triage-with-jev">Step 3: Triage with Jev</h3>
<p>Once a ticket is stored, the triage service asks Jev to classify it. Here's the heart of the Jev adapter, from <code>packages/ai/src/jev-classifier.ts</code> (trimmed a little for space):</p>
<pre><code class="language-typescript">const response = await this.client.systemOne({
  state: {
    message: input.message,
    category_hint: input.categoryHint ?? null,
  },
  questions: {
    ticket_type: choice(
      "What kind of support ticket is this? The visitor-selected category hint is a weak signal, not ground truth: judge from the message content.",
      {
        question: "The visitor asks how something works or what something is.",
        bug: "Something is broken, errors, or behaves incorrectly.",
        feature_request: "The visitor requests new functionality or an improvement.",
        spam: "Unsolicited advertising, scams, or irrelevant bulk content.",
        // ...account, billing, feedback, and other
      },
    ),
    severity: choice("How urgent is this ticket?", {
      low: "Minor inconvenience, cosmetic issue, or general question.",
      medium: "Broken functionality with a workaround, or a routine request.",
      high: "Major functionality unavailable, no workaround, time-sensitive.",
      critical: "Security breach, data loss, privacy exposure, or billing harm.",
    }),
  },
});
</code></pre>
<p><code>systemOne</code> is the TypeSafe SDK call for bounded questions. The <code>state</code> object is everything Jev is allowed to see: the message and the topic the visitor picked.</p>
<p>Notice what's missing. There's no name, no email, and no ticket ID, because none of them help with classification and all of them would be private data leaving your platform.</p>
<p>Each <code>choice</code> defines one question and its possible answers. The descriptions next to each label tell Jev what the label means. The ticket type question also tells Jev to treat the visitor's chosen topic as a weak hint, because people often pick "Report a bug" for a question, or "Ask a question" for something that's clearly broken.</p>
<p>What comes back isn't trusted automatically. The adapter validates the response with a Zod schema, checks that both answers are labels from the allowed lists, and uses the probability Jev gave to the chosen type label as the confidence score.</p>
<p>If that probability is missing or outside the range 0 to 1, the result is rejected, and the ticket stays in review instead of getting a made up number.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f46a01aa639932bd830f982/2530f001-0850-4603-8694-5125766b421c.png" alt="A ticket in the dashboard after triage: Jev classified it as a medium severity bug with a confidence of 1.00 and recommended it for GitHub" style="display: block;" width="2560" height="2802" loading="lazy">

<h3 id="heading-step-4-code-makes-the-decisions">Step 4: Code Makes the Decisions</h3>
<p>Jev recommends a type and a severity. It doesn't decide where a ticket goes or whether it becomes a GitHub issue. That job belongs to plain functions in <code>packages/ai/src/policy.ts</code>:</p>
<pre><code class="language-typescript">export function routeForType(type: TicketType): TicketRoute {
  switch (type) {
    case "bug":
      return "engineering";
    case "feature_request":
      return "product";
    case "spam":
      return "ignore";
    default:
      return "support";
  }
}

export function evaluateGitHubEscalation(input: {
  type: TicketType;
  route: TicketRoute;
  confidence: number;
}): EscalationEvaluation {
  const reasons: string[] = [];
  if (input.type !== "bug") reasons.push(`type is ${input.type}, not bug`);
  if (input.route !== "engineering") reasons.push(`route is ${input.route}, not engineering`);
  if (!(input.confidence &gt;= GITHUB_ESCALATION_CONFIDENCE_THRESHOLD)) {
    reasons.push(`confidence ${input.confidence} is below ${GITHUB_ESCALATION_CONFIDENCE_THRESHOLD}`);
  }
  return { eligible: reasons.length === 0, reasons };
}
</code></pre>
<p><code>routeForType</code> maps each ticket type to a queue. Bugs go to engineering, feature requests go to product, spam is quarantined, and everything else goes to support. Because this is a normal <code>switch</code> statement, you can read it, test it, and change it without touching the AI.</p>
<p><code>evaluateGitHubEscalation</code> decides whether a ticket is even allowed to become a GitHub issue. It must be a bug, it must be in the engineering queue, and its confidence must be at least 0.9. Instead of returning a bare <code>true</code> or <code>false</code>, it collects the reasons a ticket failed, which the dashboard shows so you always know why the <strong>Create GitHub issue</strong> button is missing.</p>
<p>The 0.9 threshold lives in one configuration file with a comment that says it's an uncalibrated starting point, not a measured accuracy. I wanted that to be honest in the code: a model score of 0.99 doesn't mean the model is right 99 percent of the time.</p>
<h3 id="heading-step-5-human-review-in-the-dashboard">Step 5: Human Review in the Dashboard</h3>
<p>Every ticket lands in a private dashboard. The projects page shows how many tickets are in each state:</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f46a01aa639932bd830f982/f9381b89-d338-48d9-8c47-e8f872674416.png" alt="The dashboard projects page showing two projects with ticket counts for each workflow state" style="display: block;" width="2560" height="1720" loading="lazy">

<p>Each project has a ticket list with filters for status, route, type, severity, and reference:</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f46a01aa639932bd830f982/f44934f1-fdd9-4c6a-ad46-f5a32d6d056f.png" alt="The ticket list for a project, with filters and a table of tickets showing their status, route, AI type, severity, and confidence" style="display: block;" width="2560" height="1720" loading="lazy">

<p>Opening a ticket shows the visitor's report, the current AI classification, the full classification history, and a timeline of everything that happened. You can run triage again, resolve the ticket, or record a review decision that changes the route, the status, or the GitHub recommendation.</p>
<p>One detail I care about: human decisions are stored in their own table, with the author and a required reason. The AI's history is never rewritten. If you override Jev, you can still see exactly what Jev said and when, which is important when you want to know how well the model is really doing.</p>
<p>The dashboard is protected by Better Auth, and every read and write is scoped to a workspace. Mutations require a same origin request, and only workspace owners can publish to GitHub.</p>
<h3 id="heading-step-6-from-bug-report-to-github-issue">Step 6: From Bug Report to GitHub Issue</h3>
<p>When a ticket passes the policy, the dashboard shows a preview of the exact issue that will be created:</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f46a01aa639932bd830f982/6b77db48-f122-4dcf-9da5-d858f7a6eb5d.png" alt="The GitHub escalation section showing a preview of the issue title and body, with the visitor's name and email absent from the issue" style="display: block;" width="2560" height="3434" loading="lazy">

<p>Look closely at that screenshot. The visitor left their name and email, and both are visible in the dashboard above, but neither appears anywhere in the issue preview.</p>
<p>That's not a coincidence. Before any issue is created, the report passes through a privacy gate in <code>packages/github/src/privacy.ts</code> that looks for email addresses, phone numbers, card numbers, private keys, API tokens, JSON web tokens, and password assignments. It also checks the report against the contact details the visitor submitted, so "Hi, Sam Visitor here" can't leak a name into a public issue. If anything is found, the preview is blocked and nothing is published.</p>
<p>When you click <strong>Create GitHub issue</strong>, a few more safeguards run:</p>
<ul>
<li><p><strong>A GitHub App, not a personal token:</strong> The App is installed only on the repositories you choose, with permission to write issues and read metadata, and nothing else.</p>
</li>
<li><p><strong>Claim first, then create:</strong> The ticket is marked as <code>creating</code> in the database before GitHub is called, so two clicks can never create two issues.</p>
</li>
<li><p><strong>A hidden marker:</strong> Each issue body ends with an opaque HTML comment tied to the ticket. If a request times out and the result is unknown, IssueRelay searches the repository for that exact marker from its own App before it ever tries again. It never blindly retries an issue it might already have created.</p>
</li>
</ul>
<img src="https://cdn.hashnode.com/uploads/covers/5f46a01aa639932bd830f982/dc142997-48e0-4b03-8046-6ad5fe4e3320.png" alt="The ticket after escalation, showing the linked GitHub issue and the escalation events in the timeline" style="display: block;" width="2560" height="2200" loading="lazy">

<p>Here's a real issue that IssueRelay created on my portfolio's public repository from a visitor report. It was created by the App's bot, labelled <code>bug</code>, and contains the report and the AI's classification, but no contact details:</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f46a01aa639932bd830f982/ec38844a-648e-4b98-b971-45edcadcf968.png" alt="A real GitHub issue created by the IssueRelay bot on a public repository, with a summary, the report, context, and a note that contact details are never published" style="display: block;" width="2560" height="2200" loading="lazy">

<h3 id="heading-step-7-keeping-github-and-the-dashboard-in-sync">Step 7: Keeping GitHub and the Dashboard in Sync</h3>
<p>The last piece closes the loop. When you close the issue on GitHub, GitHub sends a webhook to IssueRelay, and the ticket moves to resolved. Reopen the issue and the ticket goes back into the queue.</p>
<p>A webhook endpoint is public by definition, so the first thing it does is prove the request really came from GitHub. This is the verification function from <code>packages/github/src/webhook-auth.ts</code>:</p>
<pre><code class="language-typescript">export function verifyWebhookSignature(input: {
  secret: string;
  rawBody: Uint8Array;
  signatureHeader: string | null;
}): boolean {
  const { secret, rawBody, signatureHeader } = input;
  if (!secret || !signatureHeader?.startsWith("sha256=")) {
    return false;
  }
  const hex = signatureHeader.slice("sha256=".length);
  if (!/^[0-9a-f]{64}$/.test(hex)) return false;
  const expected = createHmac("sha256", secret).update(rawBody).digest();
  const actual = Buffer.from(hex, "hex");
  if (expected.length !== actual.length) return false;
  return timingSafeEqual(expected, actual);
}
</code></pre>
<p>GitHub signs every delivery with a secret that only GitHub and your platform know, and sends the signature in the <code>X-Hub-Signature-256</code> header. This function computes its own HMAC SHA256 signature over the <strong>raw request bytes</strong> and compares the two.</p>
<p>Two details are easy to get wrong. First, the signature has to be computed over the exact bytes GitHub sent, before any JSON parsing, because parsing and reformatting would change the bytes. Second, the comparison uses <code>timingSafeEqual</code>, which takes the same amount of time whether the first byte or the last byte differs, so an attacker can't guess the signature one character at a time by measuring response times. The function also returns <code>false</code> for every kind of failure without saying which one, so it leaks nothing.</p>
<p>After the signature check, IssueRelay stores each delivery ID, so a repeated delivery is ignored. It updates only an issue that belongs to the matching App installation and repository, and it applies events in the order they happened on GitHub, not the order they arrived.</p>
<h2 id="heading-how-to-deploy-your-own-issuerelay">How to Deploy Your Own IssueRelay</h2>
<p>You can run your own IssueRelay on Vercel and Neon in about 15 minutes. The complete walkthrough, including troubleshooting, is in <a href="https://github.com/andrewbaisden/issuerelay/blob/main/docs/SELF_HOSTING.md">docs/SELF_HOSTING.md</a>. Here's the short version.</p>
<h3 id="heading-step-1-deploy"><strong>Step 1: Deploy</strong></h3>
<p>The recommended path is the <strong>Deploy with Vercel</strong> button in the README. It copies the repository into your GitHub account, adds a Neon database, and asks for three random secrets.</p>
<p>The first build fails on purpose because Vercel's clone screen has no Root Directory setting, so you set Root Directory to <code>apps/web</code> in the project settings and redeploy. The production build then creates every database table for you.</p>
<p>The guide also describes a <strong>Fork and Import</strong> path that makes future updates a single click, but that path hasn't been tested end to end yet.</p>
<h3 id="heading-step-2-run-the-setup-page"><strong>Step 2: Run the Setup Page</strong></h3>
<p>Open <code>/setup</code> on your new site. It only works while the database has no accounts and you enter the <code>SETUP_TOKEN</code> you created during the deploy, so nobody who finds your URL first can claim your platform. It creates your owner account and your first project, then shows your widget key and the ready to paste widget code.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f46a01aa639932bd830f982/6b09f257-4b29-41bd-8c6b-e95db8200504.png" alt="The first run setup page with fields for the setup token, owner account, workspace, site name, and site addresses" style="display: block;" width="2560" height="2464" loading="lazy">

<p>The site address field starts with <code>http://localhost:3000</code>, which is where a Next.js app runs on your computer. Add your live address too, such as <code>https://my-site.vercel.app</code> or your own domain. If you forget, the widget will politely tell visitors "We couldn't send your message," so this is the first thing to check when a report doesn't arrive.</p>
<h3 id="heading-step-3-create-the-github-app"><strong>Step 3: Create the GitHub App</strong></h3>
<p>Setting up a GitHub App by hand has a few easy mistakes in it. The worst one is forgetting to subscribe to the Issues event, which I did myself during testing. So IssueRelay includes a command that creates the App for you from a manifest:</p>
<pre><code class="language-shell">pnpm github:create-app --platform https://your-issuerelay.vercel.app
</code></pre>
<p>This opens GitHub in your browser with everything already filled in: a private App with permission to write issues and read metadata, subscribed to the Issues event, with its webhook pointing at your platform.</p>
<p>You click <strong>Create GitHub App</strong>, GitHub redirects back to a temporary local server started by the command, and the command writes the App ID, private key, and webhook secret to a file that git ignores. It never prints them in your terminal. The terminal then lists the next setup phase.</p>
<h3 id="heading-step-4-add-your-keys-and-redeploy"><strong>Step 4: Add Your Keys and Redeploy</strong></h3>
<p>Add the three GitHub App values and your <code>TYPESAFE_API_KEY</code> to your Vercel project's environment variables, then redeploy. Jev is required for GitHub issues: without it, reports still arrive in your dashboard, but none can become an issue.</p>
<h3 id="heading-step-5-connect-your-repository"><strong>Step 5: Connect Your Repository</strong></h3>
<p>Install the App on the repository of the website where the widget will live, then open your project's <strong>Settings</strong> page in the dashboard and connect it. The page asks GitHub which installation and repository ID belong to that name, so a typo can't link the wrong repository.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5f46a01aa639932bd830f982/d7ca9ddf-9774-4031-a67e-51f4fbec8781.png" alt="The project settings page with the widget key, the ready to paste widget code, the allowed site addresses, and the connected GitHub repository" style="display: block;" width="2560" height="2626" loading="lazy">

<h3 id="heading-step-6-install-the-widget"><strong>Step 6: Install the Widget</strong></h3>
<p>Install the widget on your site with the code from the settings page, and send your first report.</p>
<p>To keep your copy up to date later, pull changes from the main repository. The guide covers the one time step needed for copies made with the Deploy button, because those copies are not GitHub forks.</p>
<h2 id="heading-running-it-on-a-real-website">Running It on a Real Website</h2>
<p>A demo is one thing, but I wanted to use IssueRelay for real, so the widget now runs on my portfolio at <a href="https://andrewbaisden.com/">andrewbaisden.com</a>:</p>
<img src="https://cdn.hashnode.com/uploads/covers/5e1e335a7a1d3fcc59028c64/2cd31d2a-b973-4e6b-a37e-6fd2fb203b7b.png" alt="The IssueRelay widget open in the corner of the author's portfolio website, over an illustrated London street scene" style="display: block;" width="2880" height="1800" loading="lazy">

<p>The website design will likely change, so if you're reading this article in the future, previous builds can be found on my GitHub.</p>
<p>Installing it taught me a few things. My portfolio was still on React 18 for its tests, while the App Router was already rendering with React 19. So I upgraded it to React 19 first and made sure every existing test passed before adding the widget. The widget matches the site's light and dark themes, sits in the bottom right corner, and has its own unit test and browser test in the portfolio repository.</p>
<p>Then I tested it like a visitor would. I sent three real reports from the live site: a question, a bug, and a feature request. Jev classified all three the way I intended, with scores between 0.95 and 1.00, and the policy routed them to support, engineering, and product. The bug became issue #3 in my public portfolio repository, which is the issue shown in the screenshot earlier. I had included my name and email with that report, and neither appears in the public issue.</p>
<h2 id="heading-testing-it-end-to-end-and-what-i-learned">Testing It End to End (and What I Learned)</h2>
<p>I didn't want a project that only worked on my machine, so testing was part of every phase instead of something saved for the end.</p>
<p>The test suite has several layers:</p>
<ul>
<li><p><strong>Unit tests</strong> for the widget, the API contract, the AI policy, the privacy gate, the setup page, and more. There are 180 of them, and none need a database.</p>
</li>
<li><p><strong>Database integration tests</strong> that run against a separate PostgreSQL test database, including concurrency tests that prove two clicks can't create two GitHub issues.</p>
</li>
<li><p><strong>Browser tests with Playwright</strong> that start their own servers on separate ports, with a separate database that is recreated for every run, so a test can never touch real data. One of those servers runs against an empty database to test the first run setup page.</p>
</li>
<li><p><strong>A package check</strong> that builds the exact npm tarball and installs it into a Vite app with a strict Content Security Policy and into a Next.js app, both outside the monorepo, then submits a report in each.</p>
</li>
<li><p><strong>A live journey test</strong> with 20 checks against a real GitHub App and a throwaway repository: submit a report, triage it, preview it, create the issue, check that no private data was published, close the issue on GitHub and wait for the webhook, reopen it, and check the timeline.</p>
</li>
</ul>
<p>I ran that live journey three times: first against my local machine through a tunnel, then against production, and finally against a completely fresh copy that I deployed by following only the setup guide. All three passed 20 out of 20.</p>
<p>More interesting than the passes, though, are the problems each stage uncovered:</p>
<ul>
<li><p><strong>The Issues event is easy to forget:</strong> The first time I created a GitHub App by hand, it had no event subscriptions, so GitHub never told IssueRelay when issues closed. That mistake is why the <code>create-app</code> command exists.</p>
</li>
<li><p><strong>Visitors mention their own names:</strong> A report like "Sarah here, the page is broken" from a visitor named Sarah would have put her name in a public issue. The privacy gate now compares every report against the contact details that came with it.</p>
</li>
<li><p><strong>Zod and strict CSP don't mix in the browser:</strong> Zod 4 briefly tests whether it can use <code>new Function</code>, and sites with a strict Content Security Policy report that as a violation. I removed Zod from the widget and wrote small validation checks instead, with a test that proves they agree with the server's Zod schemas on 270 form combinations.</p>
</li>
<li><p><strong>Vercel's clone flow has no Root Directory option, and Vercel picks the framework only once:</strong> My fresh deploy failed twice: once because Vercel built the repository root, and once because the framework was still set to "Other." The repository now pins Next.js in <code>vercel.json</code>, and the guide warns about the first failure.</p>
</li>
<li><p><strong>Deploy button copies aren't forks:</strong> A plain <code>git pull</code> from the main repository refuses to merge, so the guide now has a one time command to connect a copy to the main repository.</p>
</li>
<li><p><strong>GitHub issues need Jev:</strong> I originally listed Jev as optional. A careful review of the guide showed that without it, no real report can reach the confidence threshold. The guide and the settings page now say so clearly.</p>
</li>
<li><p><strong>Log noise matters:</strong> Every database connection logged an SSL warning at error level, which made a healthy deployment look broken. The fix was to spell out the SSL mode the driver was already using, so the warning disappeared while the certificate checks stayed exactly the same.</p>
</li>
</ul>
<p>The lesson that stuck with me most: <strong>deploying from your own documentation, word for word, finds bugs that no test will.</strong> Every one of the deployment problems above was invisible to the automated tests and obvious the moment a real person followed the guide.</p>
<h2 id="heading-how-it-was-built-phases-and-ai-assisted-development">How It Was Built: Phases and AI Assisted Development</h2>
<p>IssueRelay was built in small phases, and each phase ended with a written handoff before the next one could start:</p>
<table>
<thead>
<tr>
<th>Phase</th>
<th>Outcome</th>
</tr>
</thead>
<tbody><tr>
<td>0</td>
<td>Product definition, architecture, decisions, security, and test plans</td>
</tr>
<tr>
<td>1 and 2</td>
<td>Monorepo foundation, domain model, PostgreSQL schema, and seed data</td>
</tr>
<tr>
<td>3 and 4</td>
<td>The widget, a demo site, and the public ticket API</td>
</tr>
<tr>
<td>5 and 6</td>
<td>AI triage with Jev and the operator dashboard</td>
</tr>
<tr>
<td>7 and 8</td>
<td>Confirmed GitHub escalation and signed webhook sync</td>
</tr>
<tr>
<td>9</td>
<td>Live validation of the full journey in a throwaway repository</td>
</tr>
<tr>
<td>10</td>
<td>Production hardening</td>
</tr>
<tr>
<td>11 and 12</td>
<td>Validating and publishing the widget to npm</td>
</tr>
<tr>
<td>Deploy</td>
<td>Vercel, Neon, and Resend in production</td>
</tr>
<tr>
<td>13</td>
<td>Installing the widget on my portfolio</td>
</tr>
<tr>
<td>14 and 15</td>
<td>Dogfooding (ongoing)</td>
</tr>
<tr>
<td>16</td>
<td>Self hosting: the Deploy button, the setup page, project settings, and the App manifest command</td>
</tr>
</tbody></table>
<h3 id="heading-my-developer-setup">My Developer Setup</h3>
<p>I did most of the work in the terminal. My setup is:</p>
<ul>
<li><p>Ghostty as my terminal, running Claude Code, Codex, and OpenCode</p>
</li>
<li><p>Cursor as my editor</p>
</li>
<li><p>The native desktop apps for ChatGPT, Claude, and OpenCode</p>
</li>
</ul>
<p>My main model for building IssueRelay was <strong>Claude Opus 5.5</strong> in Claude Code. For code reviews and for checking a phase before I signed it off, I used other models, including <strong>GPT-6 Sol</strong> and Grok, along with various other frontier and free models.</p>
<p>A second model reading the same code with fresh eyes caught real problems. For example, a Grok review of Phases 7 and 8 raised 15 findings. Seven were valid, including a race in claiming issue creation and issue markers that could be guessed, and all seven were fixed before I moved on. Three more were partly valid and five were deferred with written reasons.</p>
<p>Anthropic's newly released <strong>Sonnet 5.5</strong> and OpenAI's <strong>GPT-6.1 Sol</strong> weren't used in this project.</p>
<h3 id="heading-how-better-prompts-improved-the-codebase">How Better Prompts Improved the Codebase</h3>
<p>The biggest improvement in quality didn't come from a smarter model. It came from giving the model better instructions and a better structure to work in. Here is what worked:</p>
<ul>
<li><p><strong>One phase at a time:</strong> Each prompt asked for exactly one phase with a clear outcome, and the AI wasn't allowed to start the next phase until I approved it. Small, reviewable changes were much easier to check than one giant feature.</p>
</li>
<li><p><strong>A plan before any code:</strong> For bigger phases I asked for a plan first ("Create a plan and then go ahead with it once I approve it"). Reading a plan takes two minutes. Unpicking a wrong implementation takes an afternoon.</p>
</li>
<li><p><strong>Rules that live in the repository:</strong> An <code>AGENTS.md</code> file holds the project's rules, such as "persist an accepted ticket before external AI or GitHub calls," "never publish contact data to GitHub," and "do not blindly retry an ambiguous GitHub issue creation." Every AI session reads it, so the rules don't depend on me remembering to repeat them.</p>
</li>
<li><p><strong>Honest reporting:</strong> The instructions say never to report an unrun check as passing, and every handoff records the commands that were run and their real results, including failures.</p>
</li>
<li><p><strong>Clear conditions for committing:</strong> Prompts like "commit and push when tests pass and there are no other issues" meant the full test suite ran before anything reached the main branch.</p>
</li>
<li><p><strong>Asking for proof, not promises:</strong> Instead of asking "does self hosting work?", I asked the AI to verify it by following the guide on a fresh deployment. That single request uncovered seven documentation and configuration problems.</p>
</li>
<li><p><strong>Feeding back real use:</strong> When I deployed a test site myself and wrote down everything that confused me, those notes went straight back into the guide, the setup page, and the settings page.</p>
</li>
</ul>
<h2 id="heading-publishing-the-widget-to-npm">Publishing the Widget to npm</h2>
<p>The widget is the only part of IssueRelay that is published, as <a href="https://www.npmjs.com/package/@issuerelay/widget"><code>@issuerelay/widget</code></a>. Everything else stays private inside the monorepo.</p>
<p>I didn't want to publish something that only worked inside my own workspace, so the release check builds the exact tarball that npm will receive and inspects it.</p>
<p>It must contain only five files. It must not reference private packages, Node built ins, environment variables, or anything that looks like a key. It must then install and work in two brand new apps outside the repository, one of them under a strict Content Security Policy, with zero policy violations.</p>
<p>Releases are published from GitHub Actions with npm trusted publishing and provenance, so there is no long lived npm token to leak.</p>
<p>The result is a package of about 10 KB compressed that needs no CSS setup and depends only on React and React Hook Form. The <a href="https://github.com/andrewbaisden/issuerelay/tree/main/packages/widget#readme">widget README</a> documents every prop.</p>
<h2 id="heading-what-is-next">What Is Next</h2>
<p>IssueRelay is complete for self hosting, and I'm using it every day on my portfolio. Some things I would like to explore next:</p>
<ul>
<li><p><strong>A hosted version</strong> of IssueRelay, so you could sign up and add the widget without deploying anything yourself</p>
</li>
<li><p><strong>Testing the Fork and Import path</strong> end to end so it can become the recommended way to deploy</p>
</li>
<li><p>Ideas from the roadmap, such as detecting duplicate reports, linking several reports to one issue, notifications, and syncing GitHub comments</p>
</li>
</ul>
<h2 id="heading-conclusion">Conclusion</h2>
<p>In this tutorial, you saw how to build an AI support system that turns scattered website feedback into reviewed tickets and routes confirmed bugs to GitHub. Along the way, you learned how to:</p>
<ul>
<li><p>Build an embeddable React widget that works on any site without CSS setup or style clashes</p>
</li>
<li><p>Save every report before calling any external service, so provider outages never lose data</p>
</li>
<li><p>Use Jev for bounded, validated classification that returns labels and probabilities instead of free text</p>
</li>
<li><p>Keep routing and publishing decisions in plain, testable code, with a human in the loop</p>
</li>
<li><p>Create GitHub issues safely with a GitHub App, a privacy gate, and a marker that prevents duplicates</p>
</li>
<li><p>Keep GitHub and your dashboard in sync with signed, verified webhooks</p>
</li>
<li><p>Deploy your own copy on Vercel and Neon, and test it end to end, including against your own documentation</p>
</li>
</ul>
<p>The best way to understand IssueRelay is to try it. You can <a href="https://github.com/andrewbaisden/issuerelay">explore the code on GitHub</a>, deploy your own copy with the <a href="https://github.com/andrewbaisden/issuerelay/blob/main/docs/SELF_HOSTING.md">self hosting guide</a>, and add the widget to your site with <code>npm install @issuerelay/widget</code> from <a href="https://www.npmjs.com/package/@issuerelay/widget">npm</a>. If it helps you, a star on the repository is always appreciated.</p>
 ]]>
                </content:encoded>
            </item>
        
            <item>
                <title>
                    <![CDATA[ How to Prevent Poisoned GitHub Actions Dependencies ]]>
                </title>
                <description>
                    <![CDATA[ Your workflow uses actions/checkout@v4. Today, that tag points to a vetted release. Tomorrow, a compromised maintainer or attacker moves the tag to malicious code. Your pipeline runs it with access to ]]>
                </description>
                <link>https://www.freecodecamp.org/news/how-to-prevent-poisoned-github-actions-dependencies/</link>
                <guid isPermaLink="false">6aad60c103851fe98f2df4a2</guid>
                
                    <category>
                        <![CDATA[ DevSecOps ]]>
                    </category>
                
                    <category>
                        <![CDATA[ Security ]]>
                    </category>
                
                    <category>
                        <![CDATA[ GitHub ]]>
                    </category>
                
                    <category>
                        <![CDATA[ Devops ]]>
                    </category>
                
                <dc:creator>
                    <![CDATA[ ILYAS RUFAI ]]>
                </dc:creator>
                <pubDate>Fri, 18 Sep 2026 16:03:13 +0000</pubDate>
                <media:content url="https://cdn.hashnode.com/uploads/covers/5e1e335a7a1d3fcc59028c64/c5ac930c-aa14-434e-a712-48102cc88e44.png" medium="image" />
                <content:encoded>
                    <![CDATA[ <p>Your workflow uses <code>actions/checkout@v4</code>. Today, that tag points to a vetted release. Tomorrow, a compromised maintainer or attacker moves the tag to malicious code. Your pipeline runs it with access to <code>GITHUB_TOKEN</code>.</p>
<p>Third-party <strong>Actions are dependencies</strong>. A floating tag behaves like an unpinned package dependency. If the reference changes, the workflow can execute different code without any change to your repository.</p>
<p>This article shows you how to prevent poisoned continuous integration (CI) dependencies by pinning Actions to full commit SHAs, validating those pins against release tags, restricting permitted actions, and automating reviewed updates with Dependabot.</p>
<p><strong>Who this is for:</strong> Platform and DevSecOps engineers securing GitHub Actions workflows.</p>
<p><strong>Prerequisites:</strong></p>
<ul>
<li><p>Repository admin access</p>
</li>
<li><p>Workflows using <code>uses: org/action@ref</code> syntax</p>
</li>
</ul>
<h2 id="heading-the-quick-reference">The Quick Reference:</h2>
<p>Here's what you'll learn how to do here:</p>
<ul>
<li><p>Pin every <code>uses:</code> reference to a <strong>full commit SHA</strong>, not a moving tag such as <code>@v4</code>.</p>
</li>
<li><p>Validate that each recorded SHA matches the release you reviewed before approving it.</p>
</li>
<li><p>Maintain an <strong>allowlist</strong> of permitted actions at the organization or repository level.</p>
</li>
<li><p>Enable <strong>Dependabot</strong> for GitHub Actions version bumps with review.</p>
</li>
<li><p>Prefer official or verified creators. Mirror critical actions internally if needed.</p>
</li>
<li><p>Verify pins in pull request checks before merge.</p>
</li>
</ul>
<h2 id="heading-table-of-contents">Table of Contents</h2>
<ul>
<li><p><a href="#heading-the-quick-reference">The Quick Reference</a></p>
</li>
<li><p><a href="#heading-why-floating-tags-fail">Why Floating Tags Fail</a></p>
</li>
<li><p><a href="#heading-pin-actions-to-commit-shas">Pin Actions to Commit SHAs</a></p>
</li>
<li><p><a href="#heading-validate-the-commit-shas">Validate the Commit SHAs</a></p>
</li>
<li><p><a href="#heading-enable-dependabot-for-actions">Enable Dependabot for Actions</a></p>
</li>
<li><p><a href="#heading-allowlist-actions">Allowlist Actions</a></p>
</li>
<li><p><a href="#heading-enforce-pins-in-pull-requests">Enforce Pins in Pull Requests</a></p>
</li>
<li><p><a href="#heading-vet-third-party-actions">Vet Third-Party Actions</a></p>
</li>
<li><p><a href="#heading-how-to-verify-this-works">How to Verify This Works</a></p>
</li>
<li><p><a href="#heading-when-this-breaks-down">When This Breaks Down</a></p>
</li>
<li><p><a href="#heading-conclusion">Conclusion</a></p>
</li>
<li><p><a href="#heading-references">References</a></p>
</li>
</ul>
<h2 id="heading-why-floating-tags-fail">Why Floating Tags Fail</h2>
<p>GitHub Actions lets you reference a dependency with a branch name, version tag, or commit SHA. These references don't provide the same level of stability. A branch can change at any time, and a version tag can be moved to a different commit after you review it. A commit SHA identifies one specific revision.</p>
<p>The table below compares the common reference styles and shows why a moving tag creates a supply chain risk:</p>
<table>
<thead>
<tr>
<th>Reference style</th>
<th>Risk</th>
</tr>
</thead>
<tbody><tr>
<td><code>@main</code></td>
<td>Runs whatever code is on the branch when the workflow starts</td>
</tr>
<tr>
<td><code>@v4</code></td>
<td>The tag can move, so the same label can execute different code</td>
</tr>
<tr>
<td><code>@v4.2.1</code></td>
<td>More specific, but still a mutable tag</td>
</tr>
<tr>
<td><code>@abc1234...</code> (full SHA)</td>
<td>Identifies one immutable commit</td>
</tr>
</tbody></table>
<p>The first three references fail because the name doesn't permanently identify the code that GitHub will execute. A full SHA solves that specific problem by making the workflow change only when someone changes the reference in the repository.</p>
<p><strong>Key idea:</strong> CI pipelines deserve the same dependency discipline as application code.</p>
<h2 id="heading-pin-actions-to-commit-shas">Pin Actions to Commit SHAs</h2>
<p>Pinning an Action means replacing its branch or version tag with the full SHA of the commit you reviewed. GitHub then checks out that exact revision, even if the publisher later moves the original tag.</p>
<p>This first example is <strong>bad</strong> because both references use mutable version tags. The workflow may run different Action code later without a corresponding change in your repository:</p>
<pre><code class="language-yaml">- uses: actions/checkout@v4
- uses: actions/setup-node@v4
</code></pre>
<p>This second example is <strong>good</strong> because each reference uses a full 40-character commit SHA. The comments preserve the readable release versions for maintainers, but GitHub uses the SHA rather than the comments:</p>
<pre><code class="language-yaml">- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
- uses: actions/setup-node@4992456781334f2795ae9dd169f5041797d85689 # v4.4.0
</code></pre>
<p>Find the SHA on the action's GitHub release page or:</p>
<pre><code class="language-bash">gh api repos/actions/checkout/git/ref/tags/v4.2.2 --jq '.object.sha'
</code></pre>
<p>Use the exact release tag you reviewed. Add a comment with the human-readable version for maintainability. The comment helps a reviewer, but it's not part of the security control. GitHub executes the commit identified by the SHA.</p>
<p>Don't use a shortened SHA. A full 40-character SHA makes accidental collisions and ambiguous reviews less likely.</p>
<h2 id="heading-validate-the-commit-shas">Validate the Commit SHAs</h2>
<p>A full SHA protects the workflow from a tag moving after you merge it, but you still need to validate the SHA before approving it. The release tag and commit should be reviewed together. This check compares the commit behind the reviewed tag with the commit recorded in the workflow:</p>
<pre><code class="language-bash">#!/usr/bin/env bash
set -euo pipefail

repository="actions/checkout"
release_tag="v4.2.2"
expected_sha="11bd71901bbe5b1630ceea73d27597364c9af683"

actual_sha="$({
  git ls-remote "https://github.com/${repository}.git" \
    "refs/tags/${release_tag}" "refs/tags/${release_tag}^{}"
} | awk -v tag="refs/tags/${release_tag}" '
  $2 == tag "^{}" { print $1; found = 1 }
  $2 == tag { fallback = $1 }
  END { if (!found) print fallback }
')"

if [[ "${actual_sha}" != "${expected_sha}" ]]; then
  printf 'SHA mismatch for %s %s\n' "${repository}" "${release_tag}" &gt;&amp;2
  printf 'Expected: %s\nActual:   %s\n' "${expected_sha}" "${actual_sha}" &gt;&amp;2
  exit 1
fi

printf 'Validated %s@%s\n' "${repository}" "${expected_sha}"
</code></pre>
<p>This is release-reference validation, not a claim that a repository is trustworthy. Read the action source, review its permissions, and record why you approved the dependency. For higher-assurance environments, mirror critical actions internally and validate the mirrored artifact through your normal repository controls.</p>
<h2 id="heading-enable-dependabot-for-actions">Enable Dependabot for Actions</h2>
<p>Dependabot is GitHub's automated dependency-update service. For GitHub Actions, it checks the workflow references for newer releases and opens pull requests that update them. This gives you a reviewable place to inspect and approve an Action update instead of changing pins manually or using floating tags.</p>
<p>Create <code>.github/dependabot.yml</code>:</p>
<pre><code class="language-yaml">version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
    groups:
      actions:
        patterns:
          - "*"
</code></pre>
<p>Dependabot opens pull requests when pinned SHAs have newer releases. Review and merge like application dependencies.</p>
<p>Don't configure Dependabot to merge these updates automatically until you have a review process for action changes. An update can contain new permissions, changed scripts, or a new transitive dependency.</p>
<p>For each update pull request, compare the old and new commit, inspect the action's release notes, and review changes to <code>action.yml</code> JavaScript bundles, shell scripts, and workflow permissions. Confirm that the new commit belongs to the release you intended to adopt. Run the workflow in a test repository or environment when the action handles deployment, publishing, credentials, or other high-impact operations.</p>
<p>The goal isn't to reject every update. The goal is to make the trust decision visible and repeatable. A reviewer should be able to answer three questions before merging: what code changed, why is the new version needed, and what permissions can that code use?</p>
<h2 id="heading-allowlist-actions">Allowlist Actions</h2>
<p>An Action allowlist is a repository or organization policy that limits which publishers and repositories workflows are allowed to call. It reduces the chance that a contributor introduces an unknown or unreviewed Action into a trusted pipeline.</p>
<p>Organization administrators can configure it at <strong>Settings → Actions → Policies → Allow specified actions</strong>. Choose the narrowest policy that matches your workflows, then add only the Action repositories your teams have reviewed.</p>
<p>Example allowlist patterns:</p>
<pre><code class="language-text">actions/checkout@*
actions/setup-node@*
actions/cache@*
docker/*
my-org/*
</code></pre>
<p>With this policy, Actions that don't match the approved patterns are denied. Repositories under the organization inherit the policy, subject to the organization's GitHub plan and repository settings.</p>
<p>For a single repo without an org policy, use <strong>Settings → Actions → General → Allow actions created by GitHub, and select non-GitHub actions</strong> and restrict to verified creators only.</p>
<p>An allowlist limits which action identities may run. It doesn't replace SHA pinning. A permitted action should still be referenced by a reviewed full SHA in every workflow.</p>
<h2 id="heading-enforce-pins-in-pull-requests">Enforce Pins in Pull Requests</h2>
<p>Run a workflow linter in CI and add a repository check that fails when a workflow introduces a non-SHA reference. Pin the checker itself before using it in a protected workflow. Replace the placeholder below with the full commit SHA you verified for the actionlint release you selected:</p>
<pre><code class="language-yaml">name: actionlint

on:
  pull_request:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
      - uses: rhysd/actionlint@03d0035246f3e81f36aed592ffb4bebf33a03106 # v1.7.7
        with:
          args: -color
</code></pre>
<p>Resolve the release tag, review the commit, and record the full 40-character SHA just as you did for <code>actions/checkout</code>.</p>
<p>You can also use a small check to catch common floating references. Treat this as a backup signal, not a YAML parser or a complete supply chain policy:</p>
<pre><code class="language-yaml">      - name: Reject floating action tags
        run: |
          if grep -RInE '^[[:space:]]*-?[[:space:]]*uses:[[:space:]]*[^#]+@(main|master|v[0-9]+)([[:space:]]|$)' .github/workflows/; then
            echo "Floating action refs found. Pin to full SHA."
            exit 1
          fi
</code></pre>
<p>The check should run on pull requests and on protected branches. A pull request can pass this test and still contain a malicious commit, so combine it with code review, the allowlist, and the SHA validation process.</p>
<h2 id="heading-vet-third-party-actions">Vet Third-Party Actions</h2>
<p>Before adding a community action to the allowlist:</p>
<ol>
<li><p>Read the action's <code>action.yml</code> and entry script.</p>
</li>
<li><p>Check star history, maintainer reputation, and open security issues.</p>
</li>
<li><p>Pin SHA and fork to <code>my-org/action-name</code> if the action is critical but externally maintained.</p>
</li>
</ol>
<p>Also inspect the permissions available to the workflow. An action that can read repository secrets or write releases deserves more scrutiny than an action that only formats a file. Set the workflow's top-level permissions to the minimum required, then grant additional permissions to individual jobs only when needed.</p>
<h2 id="heading-how-to-verify-this-works">How to Verify This Works</h2>
<ol>
<li><p>Run the SHA validation script for every action you approve and expect all comparisons to pass.</p>
</li>
<li><p>Open a test pull request that changes an action to<code>@main</code>, and confirm the CI gate fails.</p>
</li>
<li><p>Add a trailing comment after a floating tag and confirm your parser or linter still rejects it.</p>
</li>
<li><p>Confirm organization policy blocks a disallowed action in a test workflow.</p>
</li>
<li><p>Confirm Dependabot opens an action update pull request and that the change receives normal review.</p>
</li>
<li><p>Review the workflow run permissions and verify that the action can't access credentials it doesn't need.</p>
</li>
</ol>
<h2 id="heading-when-this-breaks-down">When This Breaks Down</h2>
<ol>
<li><p><strong>Emergency patches:</strong> SHA pinning slows hotfixes. Dependabot plus on-call review is safer than temporarily using a floating tag.</p>
</li>
<li><p><strong>Composite actions in private repos:</strong> pin internal actions the same way as public ones.</p>
</li>
<li><p><strong>Reusable workflows:</strong> pin the reusable workflow ref to SHA as well as steps inside it.</p>
</li>
<li><p><strong>Annotated tags and mirrors:</strong> resolve annotated tags to their commit before recording a SHA, and validate internal mirrors through your own change-control process.</p>
</li>
<li><p><strong>False sense of safety:</strong> pinning without reading code still trusts the maintainer at pin time. Combine pinning with allowlists, least-privilege permissions, and review.</p>
</li>
</ol>
<h2 id="heading-conclusion">Conclusion</h2>
<p>In this tutorial, you learned how to prevent poisoned CI dependencies by pinning GitHub Actions to reviewed commit SHAs, validating those references, allowlisting trusted actions, enabling Dependabot updates, and enforcing pins in pull request checks.</p>
<p>The result is a layered control: a reviewed immutable reference, a restricted set of permitted actions, automated update proposals, and a pull request check that catches regressions before merge.</p>
<h2 id="heading-references">References</h2>
<ul>
<li><p><a href="https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions">GitHub Actions, Security hardening</a></p>
</li>
<li><p><a href="https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot">GitHub, Dependabot version updates for Actions</a></p>
</li>
<li><p><a href="https://www.stepsecurity.io/blog/pinning-github-actions-for-enhanced-security">StepSecurity, Pin GitHub Actions</a></p>
</li>
<li><p><a href="https://github.com/ossf/scorecard/blob/main/docs/checks.md#pinned-dependencies">OpenSSF, Source compromise defenses</a></p>
</li>
</ul>
 ]]>
                </content:encoded>
            </item>
        
            <item>
                <title>
                    <![CDATA[ How to Fix a Leaked API Key: A Developer’s Guide to Git Security ]]>
                </title>
                <description>
                    <![CDATA[ Imagine this: you're working late, your code finally works, and you're ready to push it to GitHub. You run: git add . git commit -m "Fix API integration" git push A few minutes later, you notice some ]]>
                </description>
                <link>https://www.freecodecamp.org/news/how-to-fix-a-leaked-api-key/</link>
                <guid isPermaLink="false">6a8ddd55902e76128f1985bb</guid>
                
                    <category>
                        <![CDATA[ Git ]]>
                    </category>
                
                    <category>
                        <![CDATA[ software development ]]>
                    </category>
                
                    <category>
                        <![CDATA[ api ]]>
                    </category>
                
                    <category>
                        <![CDATA[ GitHub ]]>
                    </category>
                
                    <category>
                        <![CDATA[ Security ]]>
                    </category>
                
                <dc:creator>
                    <![CDATA[ Eva J Patel ]]>
                </dc:creator>
                <pubDate>Tue, 25 Aug 2026 18:22:13 +0000</pubDate>
                <media:content url="https://cdn.hashnode.com/uploads/covers/5e1e335a7a1d3fcc59028c64/0903575c-822b-481b-af12-07b864bebc67.png" medium="image" />
                <content:encoded>
                    <![CDATA[ <p>Imagine this: you're working late, your code finally works, and you're ready to push it to GitHub.</p>
<p>You run:</p>
<pre><code class="language-bash">git add .
git commit -m "Fix API integration"
git push
</code></pre>
<p>A few minutes later, you notice something strange. Your API usage has suddenly increased. Maybe there are unexpected requests, new cloud resources, or even a bill that looks much larger than expected.</p>
<p>Then you find it:</p>
<pre><code class="language-javascript">const apiKey = "sk_live_123456789";
</code></pre>
<p>Your API key is sitting in a Git repository.</p>
<p>This situation is stressful, but it's fixable.</p>
<p>The most important rule is:</p>
<blockquote>
<p><strong>If an API key has been committed to Git, assume it has been copied and compromised, even if you delete it immediately.</strong></p>
</blockquote>
<p>Deleting the key from the latest version of your file doesn't make the old key safe. Git keeps previous versions of files in its history, and exposed credentials can be discovered by automated scanners.</p>
<p>In this guide, you'll learn the following:</p>
<ul>
<li><p><a href="#heading-what-is-an-api-key">What Is an API Key?</a></p>
</li>
<li><p><a href="#heading-the-emergency-response-what-to-do-first">The Emergency Response: What to Do First</a></p>
</li>
<li><p><a href="#heading-step-1-revoke-or-rotate-the-leaked-key">Step 1: Revoke or Rotate the Leaked Key</a></p>
</li>
<li><p><a href="#heading-step-2-investigate-suspicious-activity">Step 2: Investigate Suspicious Activity</a></p>
</li>
<li><p><a href="#heading-step-3-remove-the-secret-from-your-current-code">Step 3: Remove the Secret From Your Current Code</a></p>
</li>
<li><p><a href="#heading-step-4-use-a-env-file-for-local-development">Step 4: Use a.envFile for Local Development</a></p>
</li>
<li><p><a href="#heading-step-5-create-a-safe-envexample">Step 5: Create a Safe.env.example</a></p>
</li>
<li><p><a href="#heading-step-6-determine-whether-the-secret-is-still-in-git-history">Step 6: Determine Whether the Secret Is Still in Git History</a></p>
</li>
<li><p><a href="#heading-when-do-you-need-to-rewrite-git-history">When Do You Need to Rewrite Git History?</a></p>
</li>
<li><p><a href="#heading-step-7-remove-the-secret-from-git-history">Step 7: Remove the Secret From Git History</a></p>
</li>
<li><p><a href="#heading-step-8-verify-that-the-secret-is-gone">Step 8: Verify That the Secret Is Gone</a></p>
</li>
<li><p><a href="#heading-step-9-push-the-cleaned-history-carefully">Step 9: Push the Cleaned History Carefully</a></p>
</li>
<li><p><a href="#heading-step-10-replace-the-credential-everywhere">Step 10: Replace the Credential Everywhere</a></p>
</li>
<li><p><a href="#heading-step-11-restrict-the-replacement-key">Step 11: Restrict the Replacement Key</a></p>
</li>
<li><p><a href="#heading-what-about-frontend-applications">What About Frontend Applications?</a></p>
</li>
<li><p><a href="#heading-environment-variables-vs-secret-managers">Environment Variables vs Secret Managers</a></p>
</li>
<li><p><a href="#heading-add-secret-scanning-to-your-workflow">Add Secret Scanning to Your Workflow</a></p>
</li>
<li><p><a href="#heading-use-git-hooks-as-an-extra-safety-net">Use Git Hooks as an Extra Safety Net</a></p>
</li>
<li><p><a href="#heading-review-your-staged-diff-before-committing">Review Your Staged Diff Before Committing</a></p>
</li>
<li><p><a href="#heading-common-mistakes-developers-make">Common Mistakes Developers Make</a></p>
</li>
<li><p><a href="#heading-a-complete-api-key-incident-checklist">A Complete API-Key Incident Checklist</a></p>
</li>
<li><p><a href="#heading-a-secure-project-structure">A Secure Project Structure</a></p>
</li>
</ul>
<p>We'll use this basic workflow throughout the article:</p>
<pre><code class="language-text">Invalidate → Investigate → Remove → Replace → Prevent
</code></pre>
<p>Let's start with what an API key actually is before we get to the most important part: what to do <strong>right now</strong> after a key is exposed.</p>
<h2 id="heading-what-is-an-api-key">What Is an API Key?</h2>
<p>An API key is a credential that allows an application to communicate with another service.</p>
<p>For example, an application might use an API key to access:</p>
<ul>
<li><p>A weather service</p>
</li>
<li><p>A payment provider</p>
</li>
<li><p>A mapping service</p>
</li>
<li><p>An artificial intelligence API</p>
</li>
<li><p>A cloud platform</p>
</li>
<li><p>A database</p>
</li>
<li><p>An email provider</p>
</li>
<li><p>A private company API</p>
</li>
</ul>
<p>A key might look something like this:</p>
<pre><code class="language-javascript">const apiKey = "your-real-api-key";
</code></pre>
<p>Or it might appear in a configuration file:</p>
<pre><code class="language-json">{
  "apiKey": "your-real-api-key",
  "databasePassword": "your-real-password"
}
</code></pre>
<p>API keys are often called <strong>secrets</strong> because possessing one may allow someone to make requests, access data, create resources, or generate charges on your account.</p>
<p>Not every API key is equally sensitive. Some services provide browser keys that are intentionally visible to users. Those keys should still have appropriate restrictions, quotas, and permissions.</p>
<p>As a general rule:</p>
<blockquote>
<p><strong>If a credential can access private data, create resources, modify records, or generate charges, it shouldn't be stored directly in your source code.</strong></p>
</blockquote>
<h2 id="heading-the-emergency-response-what-to-do-first">The Emergency Response: What to Do First</h2>
<p>When you discover a leaked credential, a common reaction is to delete the key from the file and push another commit.</p>
<p>Don't start there.</p>
<p>Your first priority is to <strong>make the leaked credential useless</strong>.</p>
<p>Use this order of operations:</p>
<pre><code class="language-text">1. Invalidate the leaked credential
2. Investigate suspicious activity
3. Remove the secret from your code
4. Replace it with a new credential
5. Clean the Git history if necessary
6. Verify the cleanup
7. Add protections against future leaks
</code></pre>
<p>Think of an API key like a house key that was dropped in a crowded street.</p>
<p>Deleting a picture of the key doesn't matter if someone already picked up the physical key.</p>
<p><strong>Change the lock first.</strong></p>
<h2 id="heading-step-1-revoke-or-rotate-the-leaked-key">Step 1: Revoke or Rotate the Leaked Key</h2>
<p>Go to the dashboard of the service that issued the credential.</p>
<p>Depending on the provider, you may see options such as:</p>
<ul>
<li><p>Revoke</p>
</li>
<li><p>Delete</p>
</li>
<li><p>Disable</p>
</li>
<li><p>Rotate</p>
</li>
<li><p>Regenerate</p>
</li>
<li><p>Create new key</p>
</li>
</ul>
<p>If the provider supports key rotation, create a replacement credential before disabling the old one if possible. This can reduce application downtime while you update your configuration.</p>
<p>The important thing is that the original credential must no longer be usable.</p>
<p><strong>Do not reuse the leaked key.</strong> Don't rename it. Don't encode it. Don't move it to another file and assume it is safe. Don't assume nobody saw it.</p>
<p>Treat it as compromised.</p>
<h2 id="heading-step-2-investigate-suspicious-activity">Step 2: Investigate Suspicious Activity</h2>
<p>After disabling the credential, check the provider's usage dashboard and logs.</p>
<p>Look for things such as:</p>
<ul>
<li><p>Sudden spikes in requests</p>
</li>
<li><p>Requests from unfamiliar locations</p>
</li>
<li><p>Unexpected database queries</p>
</li>
<li><p>New cloud resources</p>
</li>
<li><p>Changes to permissions</p>
</li>
<li><p>Unexpected downloads</p>
</li>
<li><p>Unusual payment activity</p>
</li>
<li><p>New deployments</p>
</li>
<li><p>Requests at times when your application was inactive</p>
</li>
</ul>
<p>If the credential had broad permissions, assume that anything within its permission scope <strong>MAY have been accessed or modified</strong>.</p>
<p>For example, if a cloud credential could create virtual machines, check whether unexpected machines were created.</p>
<p>If a credential could access a database, review:</p>
<ul>
<li><p>Authentication logs</p>
</li>
<li><p>Read operations</p>
</li>
<li><p>Write operations</p>
</li>
<li><p>Deleted records</p>
</li>
<li><p>Exported data</p>
</li>
<li><p>Newly created accounts</p>
</li>
<li><p>Permission changes</p>
</li>
</ul>
<p>Also check your billing information if the credential could generate usage-based charges.</p>
<p>Write down what you discover. A simple timeline can help:</p>
<pre><code class="language-text">10:15 - API key committed
10:23 - Repository pushed publicly
10:41 - Unusual usage detected
10:45 - Key revoked
11:00 - Logs reviewed
11:30 - Replacement key deployed
12:00 - Git history cleaned
</code></pre>
<p>This can be especially useful if you need to report the incident to a team or service provider.</p>
<h2 id="heading-step-3-remove-the-secret-from-your-current-code">Step 3: Remove the Secret From Your Current Code</h2>
<p>Once the original credential has been disabled, remove it from your working files.</p>
<p>This is unsafe:</p>
<pre><code class="language-javascript">const apiKey = "your-real-api-key";
</code></pre>
<p>Instead, load the credential from the environment:</p>
<pre><code class="language-javascript">const apiKey = process.env.API_KEY;

if (!apiKey) {
  throw new Error("API_KEY is not configured");
}
</code></pre>
<p>In Python:</p>
<pre><code class="language-python">import os

api_key = os.environ.get("API_KEY")

if not api_key:
    raise RuntimeError("API_KEY is not configured")
</code></pre>
<p>The important idea is simple:</p>
<pre><code class="language-text">Source code → environment variable → secret value
</code></pre>
<p>instead of:</p>
<pre><code class="language-text">Source code → hardcoded secret
</code></pre>
<p>Environment variables aren't the only way to manage secrets, but they are a common and practical solution for local development and many deployment environments.</p>
<h2 id="heading-step-4-use-a-env-file-for-local-development">Step 4: Use a <code>.env</code> File for Local Development</h2>
<p>For local development, you can store environment variables in a <code>.env</code> file.</p>
<p>For example:</p>
<pre><code class="language-env">API_KEY=your-local-development-key
DATABASE_URL=your-local-database-url
</code></pre>
<p>A Node.js project can load these values with a package such as <code>dotenv</code>.</p>
<p>Install it with:</p>
<pre><code class="language-bash">npm install dotenv
</code></pre>
<p>Then:</p>
<pre><code class="language-javascript">import "dotenv/config";

const apiKey = process.env.API_KEY;
</code></pre>
<p>The important part is that the <code>.env</code> file normally <strong>should not be committed to Git</strong>.</p>
<p>Add it to <code>.gitignore</code>:</p>
<pre><code class="language-gitignore"># Environment files
.env
.env.*
!.env.example

# Credential files
*.pem
*.key
credentials.json
service-account.json

# Local development files
.DS_Store
</code></pre>
<p>But there's an important detail here: the <code>.gitignore</code> <strong>does NOT remove files that Git is already tracking.</strong></p>
<p>If <code>.env</code> has already been committed, adding it to <code>.gitignore</code> won't erase it from Git.</p>
<p>You can stop tracking the file while keeping it on your computer:</p>
<pre><code class="language-bash">git rm --cached .env
</code></pre>
<p>Then commit the <code>.gitignore</code> change:</p>
<pre><code class="language-bash">git add .gitignore
git commit -m "Ignore local environment files"
</code></pre>
<p>But remember: this only removes the file from future commits. It does <strong>not</strong> remove the secret from previous commits.</p>
<p>That's where Git history comes in.</p>
<h2 id="heading-step-5-create-a-safe-envexample">Step 5: Create a Safe <code>.env.example</code></h2>
<p>Other developers still need to know which environment variables the application requires.</p>
<p>Instead of committing <code>.env</code>, create <code>.env.example</code>:</p>
<pre><code class="language-env">API_KEY=
DATABASE_URL=
PORT=3000
LOG_LEVEL=info
</code></pre>
<p>This file contains variable names rather than real credentials, so it can be committed to the repository.</p>
<p>You can also provide comments:</p>
<pre><code class="language-env"># Required API credential
API_KEY=

# PostgreSQL connection string
DATABASE_URL=

# Optional application port
PORT=3000
</code></pre>
<p>A new developer can then copy the file:</p>
<pre><code class="language-bash">cp .env.example .env
</code></pre>
<p>and provide their own values.</p>
<p>Use clearly fake placeholders in examples:</p>
<pre><code class="language-env">API_KEY=replace-me-with-your-own-key
</code></pre>
<p>Avoid putting realistic-looking production credentials into <code>.env.example</code>.</p>
<h2 id="heading-step-6-determine-whether-the-secret-is-still-in-git-history">Step 6: Determine Whether the Secret Is Still in Git History</h2>
<p>This is one of the most important parts of fixing a leaked credential.</p>
<p>Suppose your Git history looks like this:</p>
<pre><code class="language-text">Commit A: Add API key to config.js
Commit B: Update API integration
Commit C: Delete API key
</code></pre>
<p>Even though Commit C no longer contains the key, Commit A still does.</p>
<p>Git remembers previous versions of your files.</p>
<p>You can inspect the history of a file with:</p>
<pre><code class="language-bash">git log --all -- config.js
</code></pre>
<p>To display a file from an older commit:</p>
<pre><code class="language-bash">git show COMMIT_ID:config.js
</code></pre>
<p>You can also search Git history for a known leaked value:</p>
<pre><code class="language-bash">git log --all -S"your-leaked-key" --oneline
</code></pre>
<p>If you know the secret was committed, you should assume that it exists somewhere in the repository's history until you've verified otherwise.</p>
<h2 id="heading-when-do-you-need-to-rewrite-git-history">When Do You Need to Rewrite Git History?</h2>
<p>Not every accidental secret requires a history rewrite. Consider these situations:</p>
<h3 id="heading-the-secret-was-never-committed">The Secret Was Never Committed</h3>
<p>If the secret exists only in your working directory and was never committed, you generally don't need to rewrite history.</p>
<p>Remove it, add the appropriate file to <code>.gitignore</code>, and continue.</p>
<h3 id="heading-the-secret-was-committed-locally-but-never-pushed">The Secret Was Committed Locally But Never Pushed</h3>
<p>If the secret exists in local commits but hasn't been shared with a remote repository, you may be able to clean up those commits before pushing.</p>
<h3 id="heading-the-secret-was-pushed-to-a-remote-repository">The Secret Was Pushed to a Remote Repository</h3>
<p>Treat the credential as compromised. Revoke or rotate it immediately.</p>
<p>Then determine whether removing the secret from the repository's history is appropriate.</p>
<h3 id="heading-the-repository-was-public">The Repository Was Public</h3>
<p>Assume that someone or something may already have copied the secret.</p>
<p>This is why <strong>revocation comes before Git cleanup</strong>.</p>
<h3 id="heading-the-secret-was-in-a-private-repository">The Secret Was in a Private Repository</h3>
<p>A private repository is safer than a public repository, but it isn't a secret vault.</p>
<p>Credentials can still escape through:</p>
<ul>
<li><p>Compromised accounts</p>
</li>
<li><p>Contractors</p>
</li>
<li><p>Integrations</p>
</li>
<li><p>CI logs</p>
</li>
<li><p>Forks</p>
</li>
<li><p>Backups</p>
</li>
<li><p>Screenshots</p>
</li>
<li><p>Copied code</p>
</li>
<li><p>Pull requests</p>
</li>
</ul>
<p>So the safest rule remains:</p>
<blockquote>
<p><strong>Never intentionally commit credentials to Git, even in a private repository.</strong></p>
</blockquote>
<h2 id="heading-step-7-remove-the-secret-from-git-history">Step 7: Remove the Secret From Git History</h2>
<p>If the credential was committed, you may need to remove it from the repository's history.</p>
<p>Before rewriting history, create a backup:</p>
<pre><code class="language-bash">git clone --mirror https://github.com/your-username/your-repository.git repository-backup.git
</code></pre>
<p>A mirror clone includes branches and tags, which makes it useful for recovery if something goes wrong.</p>
<h3 id="heading-option-1-remove-an-entire-file">Option 1: Remove an Entire File</h3>
<p>If the secret was stored in a file such as <code>.env</code>, you can remove that file from the entire history:</p>
<pre><code class="language-bash">git filter-repo --path .env --invert-paths
</code></pre>
<p>For a file inside a directory:</p>
<pre><code class="language-bash">git filter-repo --path config/production.json --invert-paths
</code></pre>
<p>This removes the file from the repository's rewritten history.</p>
<h3 id="heading-option-2-replace-a-secret-inside-a-file">Option 2: Replace a Secret Inside a File</h3>
<p>Sometimes you need to keep the file but remove the secret from previous versions.</p>
<p>Create a temporary replacements file:</p>
<p>Then run:</p>
<pre><code class="language-bash">git filter-repo --replace-text replacements.txt
</code></pre>
<p>You can replace the value with a placeholder:</p>
<pre><code class="language-text">your-leaked-key==&gt;YOUR_API_KEY_HERE
</code></pre>
<p>Be extremely careful with <code>replacements.txt</code>. It contains the original secret, so <strong>do not commit it.</strong></p>
<p>Delete it after the cleanup:</p>
<pre><code class="language-bash">rm replacements.txt
</code></pre>
<p>On Windows PowerShell:</p>
<pre><code class="language-powershell">Remove-Item replacements.txt
</code></pre>
<p>For multiple secrets:</p>
<pre><code class="language-text">old-api-key==&gt;REMOVED_API_KEY
old-database-password==&gt;REMOVED_DATABASE_PASSWORD
old-token==&gt;REMOVED_TOKEN
</code></pre>
<p>Then:</p>
<pre><code class="language-bash">git filter-repo --replace-text replacements.txt
</code></pre>
<p>Test the cleanup on your backup clone first.</p>
<h2 id="heading-step-8-verify-that-the-secret-is-gone">Step 8: Verify That the Secret Is Gone</h2>
<p>Never assume the cleanup worked just because the command completed successfully.</p>
<p>Search for the known leaked value again:</p>
<pre><code class="language-bash">git log --all -S"your-leaked-key" --oneline
</code></pre>
<p>You can also inspect relevant files and commits:</p>
<pre><code class="language-bash">git log --all -- config.js
</code></pre>
<p>and:</p>
<pre><code class="language-bash">git show COMMIT_ID:config.js
</code></pre>
<p>If your repository uses branches and tags, make sure you aren't checking only the branch you currently have checked out.</p>
<p>You should also inspect other locations where the secret may have appeared, including pull requests, CI/CD logs, build artifacts, release files, Docker images, package releases, documentation, issue comments, and screenshots</p>
<p>Remember:</p>
<blockquote>
<p><strong>Rewriting your repository doesn't erase copies that already exist somewhere else.</strong></p>
</blockquote>
<p>That's another reason why the original credential must be revoked.</p>
<h2 id="heading-step-9-push-the-cleaned-history-carefully">Step 9: Push the Cleaned History Carefully</h2>
<p>Once you've verified the cleanup, you may need to push the rewritten history:</p>
<pre><code class="language-bash">git push --force --all origin
git push --force --tags origin
</code></pre>
<h3 id="heading-important-warning">Important Warning</h3>
<p><strong>Force-pushing rewritten history is disruptive.</strong> It changes commit hashes and can affect collaborators who have existing clones of the repository.</p>
<p>Before doing this on a shared project:</p>
<ol>
<li><p>Tell your collaborators.</p>
</li>
<li><p>Make sure everyone understands that history is being rewritten.</p>
</li>
<li><p>Coordinate the cleanup.</p>
</li>
<li><p>Follow your organization's incident-response process if one exists.</p>
</li>
</ol>
<p>After the rewrite, collaborators may need to reclone the repository:</p>
<pre><code class="language-bash">git clone https://github.com/your-username/your-repository.git
</code></pre>
<p>They shouldn't blindly merge their old repository history back into the cleaned repository.</p>
<h2 id="heading-step-10-replace-the-credential-everywhere">Step 10: Replace the Credential Everywhere</h2>
<p>Now create or use the replacement credential. Update every environment where the application runs. Common locations include:</p>
<ul>
<li><p>Local development</p>
</li>
<li><p>Testing</p>
</li>
<li><p>Staging</p>
</li>
<li><p>Production</p>
</li>
<li><p>Docker containers</p>
</li>
<li><p>Kubernetes secrets</p>
</li>
<li><p>CI/CD systems</p>
</li>
<li><p>Hosting platforms</p>
</li>
<li><p>Scheduled jobs</p>
</li>
<li><p>Serverless functions</p>
</li>
</ul>
<p>A common mistake is updating production but forgetting the deployment pipeline.</p>
<p>For example, your local application may work because <code>.env</code> contains the new key, while your CI/CD system still contains the old one.</p>
<p>Make a checklist:</p>
<pre><code class="language-text">1. Local development
2. Automated tests
3. Staging
4. Production
5. CI/CD variables
6. Docker configuration
7. Cloud deployment settings
8. Scheduled scripts
9. Serverless functions
</code></pre>
<p>After updating the credential, test the application in each important environment.</p>
<h2 id="heading-step-11-restrict-the-replacement-key">Step 11: Restrict the Replacement Key</h2>
<p>Replacing a leaked credential is only part of the solution.</p>
<p>The new credential should have <strong>only the permissions it actually needs</strong>.</p>
<p>Useful restrictions can include:</p>
<ul>
<li><p>Read-only permissions</p>
</li>
<li><p>Specific API scopes</p>
</li>
<li><p>Allowed IP addresses</p>
</li>
<li><p>Allowed domains</p>
</li>
<li><p>Environment-specific access</p>
</li>
<li><p>Request quotas</p>
</li>
<li><p>Rate limits</p>
</li>
<li><p>Expiration dates</p>
</li>
</ul>
<p>For example, a weather application may only need permission to read weather data.</p>
<p>It shouldn't have permission to manage users, modify billing, or delete unrelated resources.</p>
<p>This is the <strong>principle of least privilege</strong>:</p>
<blockquote>
<p><strong>Give each credential the smallest amount of access necessary to perform its job.</strong></p>
</blockquote>
<p>It's also a good idea to use different credentials for different environments:</p>
<pre><code class="language-text">local-development-key
testing-key
staging-key
production-key
</code></pre>
<p>That way, a development credential leak doesn't automatically expose production resources.</p>
<h2 id="heading-what-about-frontend-applications">What About Frontend Applications?</h2>
<p>This is where API-key security gets confusing.</p>
<p>Frontend code runs on the user's device.</p>
<p>That means users can inspect it.</p>
<p>For example:</p>
<pre><code class="language-javascript">const apiKey = "browser-key";
</code></pre>
<p>A user can inspect the JavaScript bundle, browser developer tools, or network requests and potentially see the value.</p>
<p>Some services intentionally provide browser API keys that are designed to be publicly visible.</p>
<p>Those keys should still be restricted by things such as:</p>
<ul>
<li><p>Allowed domains</p>
</li>
<li><p>Website origins</p>
</li>
<li><p>API operations</p>
</li>
<li><p>Usage quotas</p>
</li>
<li><p>Referrer restrictions</p>
</li>
<li><p>Time limits</p>
</li>
</ul>
<p>But a truly private credential should <strong>never be placed in browser code</strong>.</p>
<p>Instead of:</p>
<pre><code class="language-javascript">fetch("https://private-api.example.com/data", {
  headers: {
    Authorization: "Bearer private-secret-token"
  }
});
</code></pre>
<p>have the browser call your own backend:</p>
<pre><code class="language-javascript">fetch("/api/data");
</code></pre>
<p>Then the backend communicates with the private service:</p>
<pre><code class="language-javascript">const response = await fetch(
  "https://private-api.example.com/data",
  {
    headers: {
      Authorization: `Bearer ${process.env.PRIVATE_API_TOKEN}`
    }
  }
);
</code></pre>
<p>The backend can then return only the information the browser is allowed to receive.</p>
<p>The important distinction is:</p>
<pre><code class="language-text">Public/browser credential
        ↓
Can be visible, but should be restricted

Private credential
        ↓
Must remain on a trusted backend or secret-management system
</code></pre>
<h2 id="heading-environment-variables-vs-secret-managers">Environment Variables vs Secret Managers</h2>
<p>Environment variables are useful, but they're not a universal secret-management solution.</p>
<p>For a small application or local development environment, something like:</p>
<pre><code class="language-env">API_KEY=your-secret
</code></pre>
<p>may be perfectly reasonable.</p>
<p>For larger production systems, you may want a dedicated <strong>secret manager</strong>.</p>
<p>A secret-management system can provide features such as:</p>
<ul>
<li><p>Centralized credential storage</p>
</li>
<li><p>Access controls</p>
</li>
<li><p>Auditing</p>
</li>
<li><p>Credential rotation</p>
</li>
<li><p>Versioning</p>
</li>
<li><p>Separation between environments</p>
</li>
<li><p>Integration with deployment systems</p>
</li>
</ul>
<p>The important idea is that your source code shouldn't be responsible for storing production secrets.</p>
<p>Instead:</p>
<pre><code class="language-text">Application
    ↓
Secret management system
    ↓
Credential
</code></pre>
<p>rather than:</p>
<pre><code class="language-text">Application
    ↓
Hardcoded production credential
</code></pre>
<p>Which solution you use depends on the size and requirements of your project.</p>
<h2 id="heading-add-secret-scanning-to-your-workflow">Add Secret Scanning to Your Workflow</h2>
<p>Humans are excellent programmers and occasionally terrible search engines.</p>
<p>Automated secret scanning can catch credentials before they make it into a repository.</p>
<p>Popular tools include:</p>
<ul>
<li><p>Gitleaks</p>
</li>
<li><p>TruffleHog</p>
</li>
<li><p>detect-secrets</p>
</li>
<li><p>Pre-commit hooks</p>
</li>
<li><p>Git hosting secret scanning</p>
</li>
<li><p>CI security scanners</p>
</li>
</ul>
<p>For example, you can run Gitleaks locally:</p>
<pre><code class="language-bash">gitleaks detect --source . --verbose
</code></pre>
<p>You can also integrate secret scanning into CI.</p>
<p>A basic GitHub Actions workflow might look like this:</p>
<pre><code class="language-yaml">name: Secret Scan

on:
  push:
  pull_request:

jobs:
  scan:
    runs-on: ubuntu-latest

    steps:
      - name: Check out repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Scan for secrets
        uses: gitleaks/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
</code></pre>
<p>Review the documentation for your chosen tool and pin versions according to your project's security practices.</p>
<p>Secret scanners can produce false positives, so you may need to configure exceptions for safe test values.</p>
<p>Be careful with allowlists, though. An overly broad exception can hide a real credential.</p>
<h2 id="heading-use-git-hooks-as-an-extra-safety-net">Use Git Hooks as an Extra Safety Net</h2>
<p>You can also scan files before they're committed.</p>
<p>For example, a simple pre-commit script could search for suspicious words:</p>
<pre><code class="language-bash">#!/usr/bin/env bash

if grep -RniE "api[_-]?key|password|secret|token|private[_-]?key" . \
  --exclude-dir=.git \
  --exclude=".env.example"; then

  echo "Possible secret detected. Commit cancelled."
  exit 1
fi
</code></pre>
<p>This isn't a complete security scanner, but it can catch obvious mistakes.</p>
<p>For stronger protection, use a dedicated secret-scanning tool through a pre-commit framework.</p>
<p>The goal isn't to make committing miserable. The goal is to make accidentally publishing a credential harder.</p>
<h2 id="heading-review-your-staged-diff-before-committing">Review Your Staged Diff Before Committing</h2>
<p>One of the simplest security habits you can develop is checking what you're actually about to commit.</p>
<p>First:</p>
<pre><code class="language-bash">git status
</code></pre>
<p>Then stage only the files you intend to commit:</p>
<pre><code class="language-bash">git add src/api.js README.md
</code></pre>
<p>Now inspect the staged changes:</p>
<pre><code class="language-bash">git diff --cached
</code></pre>
<p>Look for:</p>
<ul>
<li><p>API keys</p>
</li>
<li><p>Passwords</p>
</li>
<li><p>Tokens</p>
</li>
<li><p>Private URLs</p>
</li>
<li><p>Internal hostnames</p>
</li>
<li><p>Customer data</p>
</li>
<li><p>Debug output</p>
</li>
<li><p>Personal information</p>
</li>
<li><p>Private certificates</p>
</li>
</ul>
<p>Only commit after the staged diff looks correct:</p>
<pre><code class="language-bash">git commit -m "Load API key from environment"
</code></pre>
<p>Be cautious with:</p>
<pre><code class="language-bash">git add .
</code></pre>
<p>It can stage files you never intended to publish, including <code>.env</code> files, database exports, generated files, or local configuration.</p>
<h2 id="heading-common-mistakes-developers-make">Common Mistakes Developers Make</h2>
<h3 id="heading-mistake-1-i-deleted-it-so-its-fine">Mistake 1: "I Deleted It, So It's Fine"</h3>
<p>Deleting a secret from the current version of a file doesn't delete it from Git history.</p>
<p><strong>Correct response:</strong> Revoke the credential and clean the repository history when appropriate.</p>
<h3 id="heading-mistake-2-the-repository-is-private">Mistake 2: "The Repository Is Private"</h3>
<p>Private repositories aren't vaults.</p>
<p>Credentials can still escape through compromised accounts, integrations, CI logs, forks, backups, or copied code.</p>
<p><strong>Correct response:</strong> Don't commit secrets even to private repositories.</p>
<h3 id="heading-mistake-3-ill-just-encode-it">Mistake 3: "I'll Just Encode It"</h3>
<p>These don't make a credential secret:</p>
<pre><code class="language-javascript">const key = atob("c29tZS1rZXk=");
</code></pre>
<p>or:</p>
<pre><code class="language-javascript">const key = "some-" + "secret-" + "value";
</code></pre>
<p>Encoding, splitting, renaming, or hiding a credential doesn't protect it.</p>
<p>If your application can reconstruct the credential, someone analyzing the application may be able to do the same.</p>
<h3 id="heading-mistake-4-logging-the-secret">Mistake 4: Logging the Secret</h3>
<p>Don't do this:</p>
<pre><code class="language-javascript">console.log(process.env.API_KEY);
</code></pre>
<p>Logs can be stored by your terminal, CI system, hosting provider, monitoring platform, or cloud service.</p>
<p>Instead:</p>
<pre><code class="language-javascript">console.log(
  "API key configured:",
  Boolean(process.env.API_KEY)
);
</code></pre>
<p>If you absolutely need to inspect a value during debugging, avoid printing the full credential.</p>
<p>For example:</p>
<pre><code class="language-javascript">function maskSecret(value) {
  if (!value) return "not configured";
  if (value.length &lt;= 8) return "********";

  return `${value.slice(0, 4)}...${value.slice(-4)}`;
}

console.log(maskSecret(process.env.API_KEY));
</code></pre>
<p>Even masked credentials should be handled carefully.</p>
<h3 id="heading-mistake-5-using-the-same-credential-everywhere">Mistake 5: Using the Same Credential Everywhere</h3>
<p>If local development, testing, staging, and production all use the same credential, one leak can affect everything.</p>
<p><strong>Correct response:</strong> Use separate credentials with separate permissions.</p>
<h3 id="heading-mistake-6-cleaning-only-the-current-branch">Mistake 6: Cleaning Only the Current Branch</h3>
<p>A secret can remain in:</p>
<ul>
<li><p>Old branches</p>
</li>
<li><p>Tags</p>
</li>
<li><p>Pull requests</p>
</li>
<li><p>Other references</p>
</li>
</ul>
<p><strong>Correct response:</strong> Consider the entire repository when investigating and cleaning a leaked credential.</p>
<h3 id="heading-mistake-7-forgetting-build-artifacts">Mistake 7: Forgetting Build Artifacts</h3>
<p>A secret might also appear in:</p>
<ul>
<li><p>Compiled JavaScript bundles</p>
</li>
<li><p>Docker images</p>
</li>
<li><p>Downloadable releases</p>
</li>
<li><p>Published packages</p>
</li>
<li><p>Generated documentation</p>
</li>
</ul>
<p><strong>Correct response:</strong> Revoke the credential and identify affected artifacts that may need to be removed or replaced.</p>
<h2 id="heading-a-complete-api-key-incident-checklist">A Complete API-Key Incident Checklist</h2>
<p>If you discover that you've exposed an API key, use this checklist:</p>
<pre><code class="language-text">1. Revoke or rotate the leaked key
2. Create a replacement credential
3. Restrict the replacement credential
4. Review provider logs
5. Review billing and usage
6. Check for unauthorized resources
7. Remove the key from current files
8. Add secret files to .gitignore
9. Create or update .env.example
10. Search Git history
11. Check branches and tags
12. Remove the secret from Git history if necessary
13. Verify the old secret is gone
14. Force-push cleaned history if appropriate
15. Check pull requests and forks
16. Check CI and deployment logs
17. Update local configuration
18. Update staging configuration
19. Update production configuration
20. Update CI/CD secrets
21. Run a secret scanner
22. Document the incident
23. Add preventive security checks
</code></pre>
<p>The exact steps will depend on your provider and project, but the order matters: <strong>Invalidate first. Clean up second.</strong></p>
<h2 id="heading-a-secure-project-structure">A Secure Project Structure</h2>
<p>A simple Node.js project might look like this:</p>
<pre><code class="language-text">my-project/
├── src/
│   └── api.js
├── .env
├── .env.example
├── .gitignore
├── package.json
└── README.md
</code></pre>
<p>The local <code>.env</code> file contains the actual development value:</p>
<pre><code class="language-env">API_KEY=your-local-key
</code></pre>
<p>The <code>.env.example</code> file contains no real credential:</p>
<pre><code class="language-env">API_KEY=replace-me-with-your-own-key
</code></pre>
<p>The application reads the environment variable:</p>
<pre><code class="language-javascript">import "dotenv/config";

const apiKey = process.env.API_KEY;

if (!apiKey) {
  throw new Error("Missing API_KEY environment variable");
}

export async function getData() {
  const response = await fetch(
    "https://api.example.com/data",
    {
      headers: {
        Authorization: `Bearer ${apiKey}`
      }
    }
  );

  if (!response.ok) {
    throw new Error(
      `API request failed: ${response.status}`
    );
  }

  return response.json();
}
</code></pre>
<p>And <code>.gitignore</code> keeps the local environment file out of future commits:</p>
<pre><code class="language-gitignore">.env
.env.*
!.env.example

node_modules/
</code></pre>
<p>Finally, your README can explain the setup without exposing credentials:</p>
<p>Step 1: Copy the example environment file on your bash <code>cp .env.example .env</code></p>
<p>Step 2: Add your own API key to <code>.env</code>.</p>
<p>And last but not least, start your application!</p>
<pre><code class="language-bash">npm start
</code></pre>
<h2 id="heading-final-thoughts">Final Thoughts</h2>
<p>Leaking an API key doesn't mean you're a terrible developer. It just means your development workflow needs better guardrails.</p>
<p>The important thing is knowing how to respond quickly and how to prevent the same mistake from happening again.</p>
<p>Remember the emergency formula:</p>
<pre><code class="language-text">Invalidate → Investigate → Remove → Replace → Prevent
</code></pre>
<p>The important thing is knowing how to respond quickly and how to prevent the same mistake from happening again.</p>
<ul>
<li><p>Invalidate the leaked credential so it can no longer be used.</p>
</li>
<li><p>Investigate your logs, usage, and billing to determine whether it was abused.</p>
</li>
<li><p>Remove the secret from your current code and, when necessary, from Git history.</p>
</li>
<li><p>Replace it with a new credential that has only the permissions it needs.</p>
</li>
<li><p>Prevent future leaks with environment variables, secret managers, secret scanning, and careful Git practices.</p>
</li>
</ul>
<p>Git is excellent at remembering your project's history. That's useful when you accidentally delete an important function. But it's much less useful when that history contains a password.</p>
<p>So keep your code public when appropriate. And <strong>keep your secrets somewhere else.</strong></p>
<p>Happy coding!</p>
 ]]>
                </content:encoded>
            </item>
        
            <item>
                <title>
                    <![CDATA[ How to Build a Production Architecture for Small Language Model Fleets ]]>
                </title>
                <description>
                    <![CDATA[ Lately, there's been more focus on creating specialized Small Language Models (SLMs) for high-throughput, real-time applications. But we seem to be at an impasse: we excel at fine-tuning these models, ]]>
                </description>
                <link>https://www.freecodecamp.org/news/how-to-build-a-production-architecture-for-small-language-model-fleets/</link>
                <guid isPermaLink="false">6a32f3c20533dba8baa5af51</guid>
                
                    <category>
                        <![CDATA[ small language model ]]>
                    </category>
                
                    <category>
                        <![CDATA[ GitHub ]]>
                    </category>
                
                    <category>
                        <![CDATA[ version control ]]>
                    </category>
                
                    <category>
                        <![CDATA[ mlflow ]]>
                    </category>
                
                    <category>
                        <![CDATA[ Python ]]>
                    </category>
                
                    <category>
                        <![CDATA[ Production ai ]]>
                    </category>
                
                <dc:creator>
                    <![CDATA[ Tejas Ashok ]]>
                </dc:creator>
                <pubDate>Wed, 17 Jun 2026 19:21:38 +0000</pubDate>
                <media:content url="https://cdn.hashnode.com/uploads/covers/5e1e335a7a1d3fcc59028c64/3b09fe00-d9ff-4ba6-bfec-feb3ebdb5da5.png" medium="image" />
                <content:encoded>
                    <![CDATA[ <p>Lately, there's been more focus on creating specialized Small Language Models (SLMs) for high-throughput, real-time applications. But we seem to be at an impasse: we excel at fine-tuning these models, but we're not that great at maintaining them.</p>
<p>While deploying one LLM is like managing an API dependency, deploying multiple domain-specific SLMs – say, one for PII removal, one for intent detection, and yet another for structure-based data extraction – is a different beast altogether.</p>
<p>In this article, you'll learn how to design an architecture that'll help you avoid “model rot” for your whole fleet of SLMs. In particular, we'll focus on how to:</p>
<ol>
<li><p>Set up a Model Registry that keeps track of lineage and performance of models</p>
</li>
<li><p>Implement a Gateway Pattern that can perform version-controlled routing</p>
</li>
<li><p>Develop a Manifest-based Delivery System that allows you to deploy to edges</p>
</li>
</ol>
<h3 id="heading-what-well-cover">What We'll Cover:</h3>
<ul>
<li><p><a href="#heading-prerequisites">Prerequisites:</a></p>
</li>
<li><p><a href="#heading-the-problem-model-rot-at-scale">The Problem: Model Rot at Scale</a></p>
<ul>
<li><p><a href="#heading-the-black-box-s3-bucket-problem">The "Black Box" S3 Bucket Problem</a></p>
</li>
<li><p><a href="#heading-the-finalmodelv2fixed-naming-problem">The "final_model_v2_fixed" Naming Problem</a></p>
</li>
<li><p><a href="#heading-why-this-leads-to-model-rot">Why this leads to "Model Rot"</a></p>
</li>
</ul>
</li>
<li><p><a href="#heading-how-to-build-a-model-registry">How to Build a Model Registry</a></p>
<ul>
<li><p><a href="#heading-what-is-a-model-registry">What is a Model Registry?</a></p>
</li>
<li><p><a href="#heading-why-is-this-essential-for-slm-fleets">Why is this essential for SLM Fleets?</a></p>
</li>
</ul>
</li>
<li><p><a href="#heading-step-by-step-how-to-implement-your-model-registry">Step-by-Step: How to Implement Your Model Registry</a></p>
</li>
<li><p><a href="#heading-how-to-implement-the-gateway-pattern-for-version-control">How to Implement the Gateway Pattern for Version Control</a></p>
<ul>
<li><a href="#heading-why-semantic-versioning-is-required">Why Semantic Versioning is Required</a></li>
</ul>
</li>
<li><p><a href="#heading-what-is-the-gateway-pattern">What is the Gateway Pattern?</a></p>
<ul>
<li><a href="#heading-implementation-example">Implementation Example</a></li>
</ul>
</li>
<li><p><a href="#heading-how-to-handle-edge-deployment-with-a-manifest-system">How to Handle Edge Deployment with a Manifest System</a></p>
<ul>
<li><a href="#heading-the-process-how-manifest-based-deployment-works">The Process: How Manifest-Based Deployment Works</a></li>
</ul>
</li>
<li><p><a href="#heading-why-this-matters">Why This Matters</a></p>
</li>
</ul>
<h2 id="heading-prerequisites">Prerequisites:</h2>
<p>To follow along most effectively with this tutorial, you should know Python well and have some experience working with ML models and training them. Experience with MLflow and any other Experiment Tracker would also be great.</p>
<h2 id="heading-the-problem-model-rot-at-scale"><strong>The Problem: Model Rot at Scale</strong></h2>
<h3 id="heading-the-black-box-s3-bucket-problem">The "Black Box" S3 Bucket Problem</h3>
<p>Storing model weights in an S3 bucket without an abstraction layer creates an informational void. When a model is just a binary file sitting in storage, you lose the "story" behind it.</p>
<p>The problem is that you have no way of knowing which training dataset, hyperparameters, or evaluation metrics produced that specific file. If a model starts performing poorly in production, you can't perform a Root Cause Analysis (RCA) because the "recipe" used to create the artifact is decoupled from the artifact itself.</p>
<p>This is risky, because if a team member leaves or a repository is archived, those weights become "zombie code." They're running in production, but no one knows how to retrain, reproduce, or safely replace them. This creates a state fear where no one wants to touch the model for fear of breaking the system.</p>
<h3 id="heading-the-finalmodelv2fixed-naming-problem">The "final_model_v2_fixed" Naming Problem</h3>
<p>Human-readable, "clever" names like final_model_v2_fixed are the antithesis of reproducible engineering.</p>
<p>These names are subjective and lose their meaning within weeks. Does "fixed" mean you addressed a PII leakage bug? Or did you just increase the context window? Did "v2" involve a new dataset, or was it just a change in the learning rate?</p>
<p>This naming convention forces you to manually track external spreadsheets to understand what's actually being deployed. It makes automated rollbacks and A/B testing impossible because the deployment pipeline can't programmatically infer the status, quality, or compatibility of a file named "final_model_v2_fixed."</p>
<h3 id="heading-why-this-leads-to-model-rot">Why This Leads to "Model Rot"</h3>
<p>"Model rot" occurs when your models degrade in performance because they're not being actively monitored, versioned, or updated in response to real-world data drift.</p>
<p>Using black boxes and poor naming results in various problems. First, you can't observe easily. Without metadata, you don't know when a model's performance has fallen below an acceptable threshold.</p>
<p>Also, you can't recover when there's an issue. If a new model version fails, you have no automated path back to the "last known good" state.</p>
<p>Finally, you can't scale. As you add your 6th, 10th, or 20th SLM, the lack of a standardized registry makes the system cognitively impossible for a human to manage.</p>
<p>Here's how you should approach making an AI application ready for production.</p>
<h2 id="heading-how-to-build-a-model-registry">How to Build a Model Registry</h2>
<p>A Model Registry is the "<em>Single Source of Truth</em>" for your AI infrastructure. It's more than just a storage folder. It's centralized metadata system that binds your model’s lifecycle together. Think of it as a version control system (like Git) specifically designed for ML artifacts.</p>
<h3 id="heading-what-is-a-model-registry">What is a Model Registry?</h3>
<p>At its core, a registry acts as a database and storage interface that binds three distinct layers together:</p>
<ol>
<li><p><strong>The artifact:</strong> The actual binary weights (for example, <code>.safetensors</code>, <code>.onnx</code>, or <code>.bin</code> files).</p>
</li>
<li><p><strong>The provenance:</strong> The "DNA" of the model-including the specific training code version, the hash of the training dataset, hyperparameter configurations, and environment dependencies.</p>
</li>
<li><p><strong>The performance metrics:</strong> Benchmarks, validation results, and production monitoring data attached to that specific version.</p>
</li>
</ol>
<h3 id="heading-why-is-this-essential-for-slm-fleets">Why is This Essential for SLM Fleets?</h3>
<p>When you are managing multiple domain-specific SLMs (for example, PII removal, intent detection, and data extraction), you encounter three critical operational challenges that only a registry can solve:</p>
<ol>
<li><p><strong>Eliminating configuration drift:</strong> A registry enforces <strong>canonical versioning</strong>. It ensures that every node in your fleet pulls the exact, tested artifact that was registered, preventing the "<em>it works on my machine</em>" issues where edge devices run slightly modified versions of your models.</p>
</li>
<li><p><strong>Enabling reproducibility and auditability:</strong> If a model underperforms, the registry allows you to instantly pull up the exact dataset, code, and environment used to train it. This allows you to perform Root Cause Analysis in minutes, rather than spending hours trying to reverse-engineer a black-box file.</p>
</li>
<li><p><strong>Managing complex dependencies:</strong> As your fleet grows, you will inevitably have models that rely on others (for example, a data extraction model tuned to the output of an intent classifier). A registry allows you to manage these model-to-model dependencies, ensuring that downstream models remain compatible whenever a core model is updated.</p>
</li>
</ol>
<p>To implement this effectively, you should do away with ad-hoc folders immediately. Whether you use <a href="https://mlflow.org/"><strong>MLflow</strong></a>, <a href="https://dvc.org/"><strong>DVC</strong></a>, or <a href="https://wandb.ai/site"><strong>Weights &amp; Biases</strong></a>, the goal is the same: treat your model weights as managed software assets. This turns "deployment" from a risky manual copy-paste operation into a robust, automated pipeline.</p>
<h2 id="heading-step-by-step-how-to-implement-your-model-registry">Step-by-Step: How to Implement Your Model Registry</h2>
<p>Building a registry is less about picking a specific tool and more about enforcing a version-controlled workflow. Here's how to operationalize it in your environment:</p>
<h3 id="heading-step-1-standardize-your-artifact-packaging">Step 1: Standardize Your Artifact Packaging</h3>
<p>Stop saving raw files. Instead, package your model weights alongside a <code>model_card.yaml</code> file. This file must contain the model’s unique ID, the hash of the training dataset, the Git commit hash of the training script, and the hyperparameter config.</p>
<h3 id="heading-step-2-initialize-the-central-registry">Step 2: Initialize the Central Registry</h3>
<p>Using a tool like MLflow or Weights &amp; Biases, create a project space. When you train a model, your script should automatically "log" the artifact to this registry via an API call rather than manual S3 uploads.</p>
<ul>
<li>Example: <code>registry.log_model(model_weights, metadata=params, tags={"stage": "staging"})</code></li>
</ul>
<h3 id="heading-step-3-enforce-a-promotion-lifecycle">Step 3: Enforce a "Promotion" Lifecycle</h3>
<p>Treat your registry like a CI/CD environment. A model shouldn't be "Production" by default. Implement a workflow where a model starts in <code>Development</code>, passes automated benchmark tests in <code>Staging</code>, and is only promoted to <code>Production</code> once it meets your predefined performance thresholds.</p>
<h3 id="heading-step-4-automate-metadata-tracking">Step 4: Automate Metadata Tracking</h3>
<p>Every time you run a training job, the experiment tracker should automatically capture the training duration, compute resources used, and evaluation metrics. By linking these to the model ID, you ensure that anyone on your team can click on a model version and immediately see the "proof" that it is ready for production.</p>
<p><strong>The result:</strong> You're no longer "managing files." You are querying a database of production-ready assets. When your gateway requests a model, it queries the registry for the <code>Production</code> tag, ensuring it always pulls the right version without you having to touch a single line of config manually.</p>
<img src="https://cdn.hashnode.com/uploads/covers/6a20d517f243d1ee74b464f2/c9f96611-232e-433e-85a9-4946e63b3fa6.png" alt="An MLOps architecture diagram showing the end-to-end automated pipeline process from data analysis and model development to deployment, serving, and continuous monitoring." style="display: block;" width="2732" height="2048" loading="lazy">

<p>This diagram visualizes the <strong>closed-loop MLOps lifecycle</strong>, mapping the transition from initial data exploration to production deployment.</p>
<p>It distinguishes between the experimental "DS Development" phase-where models are built and tested-and the "Automated Pipelines" stage, which ensures that models are systematically engineered, registered, and continuously monitored.</p>
<p>By highlighting the interconnectedness of the Feature Store, ML Metadata Store, and the Model Registry, the image illustrates how a production-ready system avoids "model rot" by creating a traceable, automated path from raw data to a reliable prediction service.</p>
<h2 id="heading-how-to-implement-the-gateway-pattern-for-version-control">How to Implement the Gateway Pattern for Version Control</h2>
<p>When we treat model weights as code, we stop thinking of them as static files and start treating them as versioned dependencies.</p>
<p>In a production fleet, "using code for weights" means that your deployment system no longer points to a hardcoded file path. Instead, it references a logical version identifier that maps to a specific, immutable set of weights.</p>
<h3 id="heading-why-semantic-versioning-is-required">Why Semantic Versioning is Required</h3>
<p>When you treat models like code, you must adopt <strong>Semantic Versioning (SemVer)</strong> (for example, <code>v1.2.0</code>) to prevent system instability.</p>
<ul>
<li><p><strong>Major versions</strong> (v2.0.0) indicate breaking changes, such as a change in model architecture or input feature requirements that would break downstream application code.</p>
</li>
<li><p><strong>Minor versions</strong> (v2.1.0) indicate backward-compatible improvements, like a retrained model with better performance on the same dataset.</p>
</li>
<li><p><strong>Patch versions</strong> (v2.1.1) indicate hotfixes, such as a model patched for PII leakage or security vulnerabilities.</p>
</li>
</ul>
<p>Without SemVer, your application can't programmatically determine if a new model version is "safe" to load. By using versions, you allow your automated pipelines to reject breaking updates before they ever reach production.</p>
<h2 id="heading-what-is-the-gateway-pattern">What is the Gateway Pattern?</h2>
<p>The Gateway Pattern acts as a <strong>dynamic routing layer</strong> between your application logic and your model artifacts. Instead of hardcoding a path (for example, <code>model_path = "s3://bucket/intent_v2.safetensors"</code>), your application queries a Gateway. The Gateway manages the mapping between a semantic version and the actual storage location of the weights.</p>
<p>This allows you to perform <strong>Hot-Swapping</strong>: you can update your configuration to point to a new model version, and the Gateway swaps the weights in memory with zero downtime.</p>
<h3 id="heading-implementation-example">Implementation Example</h3>
<p>Here's how you can implement a simple Python gateway to abstract away your model artifacts:</p>
<pre><code class="language-python">class ModelGateway:
    def __init__(self):
        # The gateway acts as a lookup table for model versions
        self.routes = {
            "intent-classifier": {
                "v1.0.0": "models/intent_v1.safetensors",
                "v2.0.0": "models/intent_v2.safetensors"
            },
            "active_version": "v1.0.0"
        }

    def predict(self, input_text):
        # Application logic calls the 'active_version' dynamically
        model_path = self.routes["intent-classifier"][self.routes["active_version"]]
        return self.load_and_run(model_path, input_text)

    def switch_version(self, version):
        # Hot-swap the version without redeploying the app
        if version in self.routes["intent-classifier"]:
            self.routes["active_version"] = version
            print(f"Traffic successfully routed to {version}")
        else:
            raise ValueError("Version not found in registry.")
</code></pre>
<p>The key insight here is that <code>switch_version</code> lets you swap from v1 to v2 in milliseconds. There's no downtime and no pipeline rerun. You update the config-perhaps via a remote central file or environment variable-and the gateway handles the rest.</p>
<h2 id="heading-how-to-handle-edge-deployment-with-a-manifest-system">How to Handle Edge Deployment with a Manifest System</h2>
<p>The final challenge is synchronization. When your models are running on edge devices (like laptops or local inference servers), you can't risk large, redundant downloads every time a model is updated. Instead, you should use a Manifest-based Delivery System. This ensures your fleet remains synchronized without forcing users to download gigabytes of weights for minor updates.</p>
<h3 id="heading-the-process-how-manifest-based-deployment-works">The Process: How Manifest-Based Deployment Works</h3>
<p>Think of your manifest as a "version control lockfile" for your model weights. The workflow follows these four steps:</p>
<ol>
<li><p><strong>Registry update and hash generation:</strong> When you deploy a new model version (for example, a fine-tuned LoRA adapter) to your Central Registry, the system calculates a unique hash for the new weight files.</p>
</li>
<li><p><strong>Manifest broadcasting:</strong> Your edge application periodically checks a tiny, lightweight <code>manifest.json</code> file hosted on your server. This file acts as the "source of truth," containing the canonical versions and the associated hashes of all required models.</p>
</li>
<li><p><strong>Delta synchronization:</strong> Your edge client compares the local manifest with the remote <code>manifest.json</code>. If the hashes don’t match, the client identifies exactly which weight files have changed. It then triggers a targeted download, downloading <em>only</em> the specific delta or the new weight file rather than the entire model architecture.</p>
</li>
<li><p><strong>Atomic swap:</strong> Once the new weights are downloaded, the client updates the local reference and triggers the Gateway to hot-swap to the new version in memory.</p>
</li>
</ol>
<h3 id="heading-example-the-manifest-structure">Example: The Manifest Structure</h3>
<p>A manifest file is simple, human-readable, and machine-parsable. It typically looks like this:</p>
<pre><code class="language-json">{
  "project": "intent-classifier-fleet",
  "models": {
    "intent-v2": {
      "version": "2.1.0",
      "hash": "a1b2c3d4e5f6...",
      "path": "s3://models/intent_v2.safetensors",
      "dependencies": ["base-tokenizer-v1"]
    }
  },
  "last_updated": "2026-06-15T14:30:00Z"
}
</code></pre>
<h4 id="heading-why-this-scales">Why this scales</h4>
<p>This approach mirrors how package managers like <code>npm</code> or <code>pip</code> function:</p>
<ul>
<li><p><strong>Efficiency:</strong> You never download extra, unnecessary files.</p>
</li>
<li><p><strong>Reliability:</strong> You are always certain of exactly which weight version is active on every single device in your fleet.</p>
</li>
<li><p><strong>Resilience:</strong> If a download is interrupted, the client verifies the hash of the partially downloaded file, ensuring that corrupt weights never make it into your inference pipeline.</p>
</li>
</ul>
<h2 id="heading-why-this-matters"><strong>Why This Matters</strong></h2>
<p>The end of the “one-size-fits-all” model era is here. Once you’ve established a rigid registry and routing design, you can transition your attention from repairing failed models to maximizing their efficiency.</p>
<p>Here's what you've designed throughout this article:</p>
<ol>
<li><p>An <strong>Artifact Registry</strong> that records lineage, hashing of datasets, and benchmarking for every artifact</p>
</li>
<li><p><strong>The Gateway Design</strong> Pattern that allows separating the version of a model from its source code and hotswapping it without any downtime</p>
</li>
<li><p>An <strong>Edge Delivery system</strong> based on Manifests and syncing the delta of weights between nodes</p>
</li>
</ol>
<p>Treating model weights like code is a good practice and gives you more control. Now that you know what exactly runs, why it runs, and how it can be swapped within milliseconds, you become more than just an AI developer: you can be a AI systems engineer.</p>
 ]]>
                </content:encoded>
            </item>
        
            <item>
                <title>
                    <![CDATA[ How to Use GitHub Search Like a Pro ]]>
                </title>
                <description>
                    <![CDATA[ GitHub is a popular code collaboration platform for developers. You can use it to share, manage, and contribute to open-source codebases, save and work on your own code, and more. And to be a more eff ]]>
                </description>
                <link>https://www.freecodecamp.org/news/how-to-use-github-search-like-a-pro/</link>
                <guid isPermaLink="false">6a0f57a1d8e265f60d4f8624</guid>
                
                    <category>
                        <![CDATA[ GitHub ]]>
                    </category>
                
                    <category>
                        <![CDATA[ Open Source ]]>
                    </category>
                
                    <category>
                        <![CDATA[ open source ]]>
                    </category>
                
                <dc:creator>
                    <![CDATA[ Rajdeep Singh ]]>
                </dc:creator>
                <pubDate>Thu, 21 May 2026 19:06:09 +0000</pubDate>
                <media:content url="https://cdn.hashnode.com/uploads/covers/5fc16e412cae9c5b190b6cdd/0e61e7e1-619c-4a66-b994-6a888100d0dd.png" medium="image" />
                <content:encoded>
                    <![CDATA[ <p>GitHub is a popular code collaboration platform for developers. You can use it to share, manage, and contribute to open-source codebases, save and work on your own code, and more.</p>
<p>And to be a more effective GitHub user, you'll need to know how to search within the platform.</p>
<p>This involves using qualifiers to efficiently filter through millions of repositories and billions of lines of code. Precise queries help you locate specific function definitions, projects, people, issues, pull requests, code, security vulnerabilities, or contribution opportunities.</p>
<p>In this tutorial, you'll learn how to use GitHub search, whether you're a beginner or a pro developer.</p>
<p>To enhance your learning, I've divided this article into two sections:</p>
<ol>
<li><p>Basic Search Functionality</p>
</li>
<li><p>Advanced Search Functionality</p>
</li>
</ol>
<h3 id="heading-what-well-cover">What We'll Cover:</h3>
<ul>
<li><p><a href="https://stackedit.io/app#heading-what-well-cover">What We’ll Cover:</a></p>
</li>
<li><p><a href="https://stackedit.io/app#heading-basic-search-functionality">Basic Search Functionality</a></p>
<ul>
<li><p><a href="https://stackedit.io/app#heading-how-to-search-globally">How to Search Globally</a></p>
</li>
<li><p><a href="https://stackedit.io/app#heading-how-to-do-a-scoped-search-for-a-particular-repo-or-organization">How to Do a Scoped Search (for a Particular Repo or Organization)</a></p>
</li>
</ul>
</li>
<li><p><a href="https://stackedit.io/app#heading-advanced-search-functionality">Advanced Search Functionality</a></p>
<ul>
<li><p><a href="https://stackedit.io/app#heading-search-qualifiers">Search Qualifiers</a></p>
</li>
<li><p><a href="https://stackedit.io/app#heading-how-to-save-searches">How to Save Searches</a></p>
</li>
<li><p><a href="https://stackedit.io/app#heading-how-to-manage-saved-searches-on-github">How to Manage Saved Searches on GitHub</a></p>
</li>
<li><p><a href="https://stackedit.io/app#heading-why-do-we-need-github-advanced-search">Why Do We Need GitHub Advanced Search?</a></p>
</li>
</ul>
</li>
<li><p><a href="https://stackedit.io/app#heading-conclusion">Conclusion</a></p>
</li>
</ul>
<h2 id="heading-basic-search-functionality">Basic Search Functionality</h2>
<p>Basic search here refers to the most commonly used search functionalities that are fast and easy to use.</p>
<p>To start, click the GitHub search icon, type your query, and GitHub will display your results. With basic search, you can search globally across all of GitHub or narrow your search to a specific repository or organization.</p>
<h3 id="heading-how-to-search-globally">How to Search Globally</h3>
<p>To search on GitHub, click the search tab or press the <code>/</code> key to open the search bar.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5dd3ab9cc4d1027248f20c91/32ae027d-4d34-4200-b2ae-da12ec67afcf.png" alt="Open search bar input filed on github" style="display: block;" width="1904" height="515" loading="lazy">

<p>To search globally (across all of GitHub), open the search input, type your query, and select "Search all of GitHub" from the dropdown menu or press enter.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5dd3ab9cc4d1027248f20c91/1de2af9b-c281-463a-ac60-08322d121e84.png" alt="global search on github" style="display: block;" width="1920" height="961" loading="lazy">

<p>After clicking the "Search all of GitHub" button, you'll be directed to a page displaying all results related to your query.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5dd3ab9cc4d1027248f20c91/8ea8f5cb-04e8-4376-9e15-f6258f216cc6.png" alt="display all results related to your query in Github" style="display: block;" width="1920" height="961" loading="lazy">

<h3 id="heading-how-to-do-a-scoped-search-for-a-particular-repo-or-organization">How to Do a Scoped Search (for a Particular Repo or Organization)</h3>
<p>To search within a specific repository or organization, go to the repository or organization page, enter your query in the search field at the top, and press Enter.</p>
<p>For instance, if you're searching for a file name starting with "pnpm" in the <a href="https://github.com/frontendweb3/frontendweb">frontendweb</a> repository:</p>
<img src="https://cdn.hashnode.com/uploads/covers/5dd3ab9cc4d1027248f20c91/5b714b9d-157c-4c0f-a710-fef3fa2365d1.png" alt="Scoped Search in Github" style="display: block;" width="1920" height="961" loading="lazy">

<p>In the search bar, you'll see four suggestions: the first is "Search in this repository," the second is "Search in this organization," the third is "Search all of GitHub," and the last is the code section "Display similar files." Clicking a file opens it in the GitHub web editor.</p>
<h2 id="heading-advanced-search-functionality">Advanced Search Functionality</h2>
<p>In addition to the GitHub search bar, you can search on GitHub using the <a href="https://github.com/search/advanced">advanced search</a> page.</p>
<p>GitHub's advanced search allows you to find specific code, repositories, and issues. You can filter your searches by factors such as the number of stars, owners, forks, followers, programming language, and creation dates.</p>
<p>As you complete the advanced search fields, your query is automatically generated in the top search bar, and you can click on the Search button.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5dd3ab9cc4d1027248f20c91/518efaf5-f3c0-48bb-a374-e00d31fc5a84.png" alt="GitHub advanced search page" style="display: block;" width="1920" height="961" loading="lazy">

<p>For a basic example, let's search for <strong>React</strong> on GitHub, including recent pull and push requests, issues, commits, discussions, and so on, related to ReactJS. We can use GitHub's advanced search functionality for this. Type "React" in the first input field as text and add the owner, in this case, Facebook, to find everything related to ReactJS in the Facebook organization or user.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5dd3ab9cc4d1027248f20c91/df1c1c8b-3bff-4f77-a008-4659280d9c92.png" alt="Basic example of GitHub's advanced search functionality." style="display: block;" width="1920" height="2167" loading="lazy">

<p>After clicking on the Search button, you should see the following results page:</p>
<img src="https://cdn.hashnode.com/uploads/covers/5dd3ab9cc4d1027248f20c91/b6c638c5-15a1-491e-9304-a6b070203773.png" alt="Show the query result of GitHub's advanced search" style="display: block;" width="1920" height="961" loading="lazy">

<p>As you can see, GitHub's advanced search functionality lets you find specific code, repositories and issues using a powerful set of qualifiers and options. Let's talk more about qualifiers now.</p>
<h3 id="heading-search-qualifiers">Search Qualifiers</h3>
<p>You can filter your search directly using various key qualifiers. We can divide these qualifiers into different sections:</p>
<h4 id="heading-advanced-options">Advanced Options</h4>
<ul>
<li><p><strong>From these owners</strong>: type the specific user's or organization's name, such as GitHub, Atom, Electron, Octokit, and so on.</p>
</li>
<li><p><strong>In these repositories</strong>: type the specific user's or organization's name, such as Facebook/React, Vercel/Next.js, and so on.</p>
</li>
<li><p><strong>Created on these dates</strong>: Specify the repository creation date, for example <code>&gt;2016-04-29</code>, <code>=2016-04-29</code>, etc., to learn more, check out the <a href="https://docs.github.com/en/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax#query-for-dates"><strong>Query for dates</strong></a> documentation.</p>
</li>
<li><p><strong>Written in this language</strong>: Select the specific language that matches repositories from lists: JavaScript, TypeScript, Rust, and so on, or what it’s written in.</p>
</li>
</ul>
<h4 id="heading-repository-options">Repository Options</h4>
<ul>
<li><p><strong>With this many stars</strong>: Type the number of stars in the <code>stars:</code> field to filter and find repositories by star count. You can apply comparisons like &gt;1000 (more than 1000 stars) or =1000 (exactly 1000 stars) to narrow results based on popularity.</p>
</li>
<li><p><strong>With this many forks</strong>: Type the number of forks to filter and find repositories by fork count. You can apply comparisons like 100..1000 (find repos with 100 to 1000 forks), &gt;1000 (more than 1000 forks), or =1000 (exactly 1000 forks) to narrow results based on popularity.</p>
</li>
<li><p><strong>Of this size</strong>: type the repository size in KB to filter and find repositories, for example, size of 10000 KB</p>
</li>
<li><p><strong>Pushed to</strong>: type the date to filter and find repositories, for example &gt;2013-02-01 matches repositories with the word "react" that were pushed to after January 2013.</p>
</li>
<li><p><strong>With this license</strong>: Select the license to filter or find repositories based on license, for example, those licensed under the Apache License 2.0.</p>
</li>
</ul>
<h4 id="heading-code-options">Code Options</h4>
<ul>
<li><p><strong>With this extension</strong>: type the extension, such as rb, py, or jpg, that you want to search on GitHub.</p>
</li>
<li><p><strong>In this path</strong>: Type the path to filter on GitHub to search for files by their location within a repository. For example, you can find a header.tsx file specifically inside the <code>./components</code> folder by combining filename: with path:.</p>
</li>
<li><p><strong>With this file name</strong>: Type the file name, such as app, footer, or header, that you want to search on GitHub.</p>
</li>
</ul>
<h4 id="heading-issue-options">Issue Options</h4>
<ul>
<li><p><strong>In the state</strong>: Select the issue state (whether the issue is open or closed), for example, libraries <code>state:open mentions:rajdeep</code> matches open issues that mention @rajdeep with the word "libraries," or <code>language:JavaScript state:open</code> matches open issues in JavaScript repositories.</p>
</li>
<li><p><strong>With this many comments</strong>: Enter the comment number based on the comment count. You can filter the issue, for example, <code>state:closed comments:&gt;100</code> matches closed issues with more than 100 comments, or <code>comments:500..1000</code> matches issues with comments ranging from 500 to 1,000.</p>
</li>
<li><p><strong>With the labels</strong>: Enter the label to filter or narrow your results by labels. Since issues can have multiple labels, you can list and add multiple label qualifiers for each issue.</p>
<p>For example, first, <code>label:bug label:resolved</code> matches issues with the labels "bug" and "resolved." Second, <code>label:bug,resolved</code> matches issues with the label "bug" or the label "resolved." Third, example <code>broken in:body -label:bug label:priority</code> matches issues with the word "broken" in the body, that lack the label "bug," but do have the label "priority."</p>
</li>
<li><p><strong>Opened by the author</strong>: Enter the name or username to filter or find issues created by a user or integration account, or filter the issues based on the author.</p>
<p>For example, <code>author:rajdeep</code> matches issues with the word "fixed" that were created by @rajdeep, or <code>author:octocat</code> matches issues created by the account named "octocat."</p>
</li>
<li><p><strong>Mentioning the users</strong>: Enter the name or username to find issues that mention the user. For example, fixed mentions:rajdeep matches issues with the word "fixed" that mention @rajdeep in the issue.</p>
</li>
<li><p><strong>Assigned to the users</strong>: Enter the name or username to find or filter issues based on the specific username assigned to the issue. For example, <code>state:open assignee:rajdeep</code> matches open issues that are assigned to @rajdeep.</p>
</li>
<li><p><strong>Updated before the date</strong>: Enter the date, filter issues based on the time of creation, or when they were last updated.</p>
<p>For example <code>language:c# created:&lt;2011-01-01 state:open</code> matches open issues that were created before 2011 in repositories written in C# or <code>weird in:body updated:&gt;=2013-02-01</code> matches issues with the word "weird" in the body that were updated after February 2013.</p>
</li>
</ul>
<h4 id="heading-user-options">User Options</h4>
<ul>
<li><p><strong>With this full name</strong>: Enter a full name to filter repositories whose name includes “rajdeep singh” on GitHub.</p>
</li>
<li><p><strong>From this location</strong>: Enter a location to find users on GitHub. For example, <code>location:russia language:javascript</code> returns users based in Russia whose repositories are primarily written in JavaScript.</p>
</li>
<li><p><strong>With this many followers</strong>: Enter a follower count to filter users by popularity. For example, <code>followers:&gt;=1000</code> finds users with 1,000 or more followers, while <code>followers:1..10 rajdeep</code> returns users with 1–10 followers whose name includes “rajdeep” on GitHub.</p>
</li>
<li><p><strong>With this many public repositories</strong>: Enter a repository count to filter users by the number of public repositories they have. For example, repos:&gt;10 finds users with more than 10 repositories, while repos:10..30 returns users who have between 10 and 30 public repositories on GitHub.</p>
</li>
<li><p><strong>Working in this language</strong>: Select the language to find users based on the primary languages of their repositories. For example, <code>language:javascript location:russia</code> returns users in Russia whose repositories are mostly written in JavaScript, while <code>language:javascript fullname:rajdeep</code> finds users with JavaScript repositories whose full name includes "rajdeep" on GitHub.</p>
</li>
</ul>
<h4 id="heading-wiki-options">Wiki Options</h4>
<ul>
<li><strong>Updated before the date</strong>: Enter a date to filter wiki pages containing “next.js” that were last updated after <code>2016-01-01</code> in your GitHub wiki.</li>
</ul>
<p>The best way to use advanced search qualifiers is to combine one or multiple qualifier/search options to achieve the best result.</p>
<h3 id="heading-how-to-save-searches">How to Save Searches</h3>
<p>I don't often use GitHub Advanced Search, but I used it to find open-source projects to learn from and contribute to. If you take a moment to fill in the information in GitHub Advanced Search, you can save the search for future use:</p>
<img src="https://cdn.hashnode.com/uploads/covers/5dd3ab9cc4d1027248f20c91/323b109b-4a7d-4aaa-a7d0-c4e15cdd1f19.png" alt="Save the query result to GitHub" style="display: block;" width="1920" height="961" loading="lazy">

<p>Enter the name and click the "Create saved search" button:</p>
<img src="https://cdn.hashnode.com/uploads/covers/5dd3ab9cc4d1027248f20c91/776a4684-ded9-433b-a35f-8cb28bec3a85.png" alt="Follow these steps to save the query results on GitHub." style="display: block;" width="1920" height="961" loading="lazy">

<p>You can show a list of all your saved searches:</p>
<img src="https://cdn.hashnode.com/uploads/covers/5dd3ab9cc4d1027248f20c91/33c4f651-d325-4ea1-87a6-9663d3932881.png" alt="List of saved query results on GitHub." style="display: block;" width="1920" height="961" loading="lazy">

<h3 id="heading-how-to-manage-saved-searches-on-github">How to Manage Saved Searches on GitHub</h3>
<img src="https://cdn.hashnode.com/uploads/covers/5dd3ab9cc4d1027248f20c91/3d9b99d8-9763-4490-8e7f-4669c1b95ece.png" alt="Manage Saved Searches on GitHub" style="display: block;" width="1920" height="961" loading="lazy">

<p>To manage a saved search, open the search bar and type "saved:" in the search bar, then click the "Manage saved searches" button.</p>
<img src="https://cdn.hashnode.com/uploads/covers/5dd3ab9cc4d1027248f20c91/68616625-8c23-4f3d-90d2-e6e6b7b6568d.png" alt="Delete and edit the saved searches on GitHub." style="display: block;" width="1920" height="961" loading="lazy">

<p>To edit a saved search, click the pencil icon next to it. To delete a saved search, click the trash icon.</p>
<h3 id="heading-why-do-we-need-github-advanced-search">Why Do We Need GitHub Advanced Search?</h3>
<p>As mentioned, GitHub Advanced Search helps you find the best issues to contribute to in open source repositories.</p>
<p>For example, I'm an expert in Next.js and React.js, and I can use GitHub Advanced Search to locate suitable issues in open-source projects for contribution.</p>
<p>Even as a beginner developer, you can use GitHub Advanced Search to find "good first issues" labeled by maintainers, making it easier to contribute.</p>
<h2 id="heading-conclusion">Conclusion</h2>
<p>GitHub Advanced Search is versatile. t's not just for searching but also for researching recent issues, pull requests, and push requests that may be related to your query, repository, user, or anything else. My favorite use is finding open-source contribution opportunities with GitHub Advanced Search.</p>
 ]]>
                </content:encoded>
            </item>
        
            <item>
                <title>
                    <![CDATA[ How to Build an Agentic Terminal Workflow with GitHub Copilot CLI and MCP Servers ]]>
                </title>
                <description>
                    <![CDATA[ Most developers live in their terminal. You run commands, debug pipelines, manage infrastructure, and navigate codebases, all from a shell prompt. But despite how central the terminal is to developer  ]]>
                </description>
                <link>https://www.freecodecamp.org/news/how-to-build-an-agentic-terminal-workflow-with-github-copilot-cli-and-mcp-servers/</link>
                <guid isPermaLink="false">69f212526e0124c05e1857b5</guid>
                
                    <category>
                        <![CDATA[ Developer Tools ]]>
                    </category>
                
                    <category>
                        <![CDATA[ AI ]]>
                    </category>
                
                    <category>
                        <![CDATA[ GitHub ]]>
                    </category>
                
                    <category>
                        <![CDATA[ terminal ]]>
                    </category>
                
                    <category>
                        <![CDATA[ mcp ]]>
                    </category>
                
                    <category>
                        <![CDATA[ mcp server ]]>
                    </category>
                
                <dc:creator>
                    <![CDATA[ Caleb Mintoumba ]]>
                </dc:creator>
                <pubDate>Wed, 29 Apr 2026 14:14:42 +0000</pubDate>
                <media:content url="https://cdn.hashnode.com/uploads/covers/5e1e335a7a1d3fcc59028c64/3e4e3d7e-6cbf-4742-a63b-f9a2579f2318.png" medium="image" />
                <content:encoded>
                    <![CDATA[ <p>Most developers live in their terminal. You run commands, debug pipelines, manage infrastructure, and navigate codebases, all from a shell prompt.</p>
<p>But despite how central the terminal is to developer workflows, AI assistance there has remained shallow: autocomplete a command here, explain an error there.</p>
<p>That changes when you combine GitHub Copilot CLI with MCP (Model Context Protocol) servers. Instead of an AI that reacts to isolated prompts, you get a terminal that understands your project context, queries live data sources, and chains tool calls autonomously – what the industry is starting to call an agentic workflow.</p>
<p>In this tutorial, you'll learn exactly how to wire these two systems together, step by step. By the end, your terminal will be able to do things like understand your Git history before suggesting a fix, query your running Docker containers before writing a compose patch, or pull live API schemas before generating a request.</p>
<h3 id="heading-table-of-contents">Table of Contents</h3>
<ul>
<li><p><a href="#heading-prerequisites">Prerequisites</a></p>
</li>
<li><p><a href="#heading-what-is-github-copilot-cli">What is GitHub Copilot CLI?</a></p>
</li>
<li><p><a href="#heading-what-is-the-model-context-protocol">What is the Model Context Protocol?</a></p>
</li>
<li><p><a href="#heading-how-mcp-servers-work-in-a-terminal-context">How MCP Servers Work in a Terminal Context</a></p>
</li>
<li><p><a href="#heading-step-1-install-and-configure-github-copilot-cli">Step 1 – Install and Configure GitHub Copilot CLI</a></p>
</li>
<li><p><a href="#heading-step-2-set-up-your-first-mcp-server">Step 2 – Set Up Your First MCP Server</a></p>
</li>
<li><p><a href="#heading-step-3-wire-copilot-cli-to-your-mcp-server">Step 3 – Wire Copilot CLI to Your MCP Server</a></p>
</li>
<li><p><a href="#heading-step-4-build-a-real-agentic-workflow">Step 4 – Build a Real Agentic Workflow</a></p>
</li>
<li><p><a href="#heading-step-5-extend-with-multiple-mcp-servers">Step 5 – Extend with Multiple MCP Servers</a></p>
</li>
<li><p><a href="#heading-debugging-common-issues">Debugging Common Issues</a></p>
</li>
<li><p><a href="#heading-conclusion">Conclusion</a></p>
</li>
</ul>
<h3 id="heading-prerequisites">Prerequisites</h3>
<p>Before you start, make sure you have the following:</p>
<ul>
<li><p><strong>Node.js</strong> v18 or later (<code>node --version</code>)</p>
</li>
<li><p><strong>npm</strong> v9 or later</p>
</li>
<li><p>A GitHub account with Copilot enabled. The free tier (available to all GitHub users) is sufficient to follow this tutorial. Pro, Business, and Enterprise plans unlock higher usage limits but aren't required.</p>
</li>
<li><p><strong>GitHub CLI</strong> (<code>gh</code>) installed. We'll use it to authenticate.</p>
</li>
<li><p>Basic familiarity with the terminal and JSON configuration files</p>
</li>
<li><p>(Optional) <strong>Docker</strong> installed if you want to follow the Docker MCP example in Step 5</p>
</li>
</ul>
<p>You don't need prior experience with MCP or agentic AI systems, as this guide builds that understanding from the ground up.</p>
<h2 id="heading-what-is-github-copilot-cli">What is GitHub Copilot CLI?</h2>
<p>GitHub Copilot CLI is the terminal-native interface to GitHub's Copilot AI. Unlike the IDE plugin (which assists with code completion), Copilot CLI is designed specifically for shell workflows. It exposes three main commands:</p>
<ul>
<li><p><code>gh copilot suggest</code> proposes a shell command based on a natural language description</p>
</li>
<li><p><code>gh copilot explain</code> explains what a given command does</p>
</li>
<li><p><code>gh copilot alias</code> generates shell aliases for Copilot subcommands</p>
</li>
</ul>
<p>Here's a quick example of <code>suggest</code> in action:</p>
<pre><code class="language-shell">gh copilot suggest "find all files modified in the last 24 hours and larger than 1MB"
</code></pre>
<p>Copilot will return something like:</p>
<pre><code class="language-shell">find . -mtime -1 -size +1M
</code></pre>
<p>It will also ask if you want to copy it, run it directly, or revise the request. This interactive loop is already useful – but by itself, Copilot CLI has no awareness of your project context. It doesn't know your repo structure, your running services, or your deployment environment. That's where MCP comes in.</p>
<h2 id="heading-what-is-the-model-context-protocol">What is the Model Context Protocol?</h2>
<p>The <strong>Model Context Protocol (MCP)</strong> is an open standard introduced by Anthropic in late 2024. Its goal is straightforward: give AI models a standardized way to connect to external tools, data sources, and services.</p>
<p>Think of MCP as a universal adapter layer between an AI model and the real world. Without MCP, each AI integration is custom-built: one plugin for GitHub, another for Postgres, another for Slack, all with incompatible interfaces. MCP defines a single protocol that any tool can implement, and any compatible AI client can consume.</p>
<p>An MCP server exposes <strong>tools</strong> (functions the AI can call), <strong>resources</strong> (data the AI can read), and <strong>prompts</strong> (reusable instruction templates). The AI client in our case, a Copilot-powered terminal discovers these capabilities at runtime and uses them autonomously to complete a task.</p>
<p>A few notable MCP servers that are already production-ready:</p>
<table>
<thead>
<tr>
<th>MCP Server</th>
<th>What it exposes</th>
</tr>
</thead>
<tbody><tr>
<td>@modelcontextprotocol/server-filesystem</td>
<td>Read/write access to local files</td>
</tr>
<tr>
<td>@modelcontextprotocol/server-git</td>
<td>Git log, diff, blame, branch operations</td>
</tr>
<tr>
<td>@modelcontextprotocol/server-github</td>
<td>GitHub Issues, PRs, repos via API</td>
</tr>
<tr>
<td>@modelcontextprotocol/server-postgres</td>
<td>Live query execution on a Postgres DB</td>
</tr>
<tr>
<td>@modelcontextprotocol/server-docker</td>
<td>Container inspection, logs, stats</td>
</tr>
</tbody></table>
<p>The full registry lives at <code>github.com/modelcontextprotocol/servers</code>.</p>
<h2 id="heading-how-mcp-servers-work-in-a-terminal-context">How MCP Servers Work in a Terminal Context</h2>
<p>Before we get hands-on, it's worth understanding the communication model.</p>
<p>MCP servers run as local processes. They communicate with the AI client over <strong>stdio</strong> (standard input/output) or over an <strong>HTTP/SSE transport</strong>. The client sends JSON-RPC messages to the server, and the server responds with structured data.</p>
<p>Here's the simplified flow:</p>
<img src="https://cdn.hashnode.com/uploads/covers/66f71ee288cc311f84e563bc/e1844dc5-a869-4201-ad8a-fd1cb305f646.png" alt="An architectural flowchart illustrating the Model Context Protocol (MCP) workflow. The process starts with a user typing a natural language prompt, passes through the Copilot CLI (the MCP client), communicates via JSON-RPC over stdio with an MCP Server (e.g., server-git), executes real tools like git log, returns a structured result to Copilot, which finally synthesizes a context-aware response for the user." style="display: block;" width="1408" height="768" loading="lazy">

<p>The key word here is <strong>grounded</strong>. Without MCP, Copilot responds based purely on its training data and your prompt. With MCP, it can call <code>git log --oneline -20</code> before answering your question about recent regressions and its answer is based on <em>your actual code history</em>, not a generalized assumption.</p>
<h3 id="heading-step-1-install-and-configure-github-copilot-cli">Step 1 – Install and Configure GitHub Copilot CLI</h3>
<p>If you haven't already, install the GitHub CLI:</p>
<pre><code class="language-shell"># macOS
brew install gh

# Ubuntu/Debian
sudo apt install gh

# Windows (via winget)
winget install --id GitHub.cli
</code></pre>
<p>Then authenticate:</p>
<pre><code class="language-shell">gh auth login
</code></pre>
<p>Follow the interactive prompts. Select <strong>GitHub.com</strong>, then <strong>HTTPS</strong>, and authenticate via browser when prompted.</p>
<p>Now install the Copilot CLI extension:</p>
<pre><code class="language-shell">gh extension install github/gh-copilot
</code></pre>
<p>Verify the installation:</p>
<pre><code class="language-shell">gh copilot --version
</code></pre>
<p>You should see output like <code>gh-copilot version 1.x.x</code>.</p>
<p><strong>Optional but recommended: set up shell aliases.</strong> This makes the workflow much faster. For <code>bash</code> or <code>zsh</code>:</p>
<pre><code class="language-shell"># Add to your ~/.bashrc or ~/.zshrc
eval "$(gh copilot alias -- bash)"   # for bash
eval "$(gh copilot alias -- zsh)"    # for zsh
</code></pre>
<p>After reloading your shell (<code>source ~/.bashrc</code>), you can use <code>ghcs</code> as shorthand for <code>gh copilot suggest</code> and <code>ghce</code> for <code>gh copilot explain</code>.</p>
<h3 id="heading-step-2-set-up-your-first-mcp-server">Step 2 – Set Up Your First MCP Server</h3>
<p>We'll start with <code>server-git</code>. It's the most immediately useful for a development workflow and has zero external dependencies.</p>
<p>Install it globally via npm:</p>
<pre><code class="language-shell">npm install -g @modelcontextprotocol/server-git
</code></pre>
<p>Test that it runs:</p>
<pre><code class="language-shell">mcp-server-git --version
</code></pre>
<p>This server exposes the following tools to any compatible MCP client:</p>
<ul>
<li><p><code>git_log</code> retrieve commit history with filters</p>
</li>
<li><p><code>git_diff</code> diff between branches or commits</p>
</li>
<li><p><code>git_status</code> current working tree status</p>
</li>
<li><p><code>git_show</code> inspect a specific commit</p>
</li>
<li><p><code>git_blame</code> annotate file lines with commit info</p>
</li>
<li><p><code>git_branch</code> list or switch branches</p>
</li>
</ul>
<p>Now create a configuration file. MCP clients look for a file called <code>mcp.json</code> to discover available servers. Create it in your project root or in a global config directory:</p>
<pre><code class="language-shell">mkdir -p ~/.config/mcp
touch ~/.config/mcp/mcp.json
</code></pre>
<p>Add the following content:</p>
<pre><code class="language-markdown">{
  "mcpServers": {
    "git": {
      "command": "mcp-server-git",
      "args": ["--repository", "."],
      "transport": "stdio"
    }
  }
}
</code></pre>
<p>A few notes on this config:</p>
<ul>
<li><p><code>command</code> is the binary to run. Make sure it's on your <code>$PATH</code>.</p>
</li>
<li><p><code>args</code> passes <code>--repository .</code> so the server scopes itself to the current working directory.</p>
</li>
<li><p><code>transport: "stdio"</code> means communication happens over standard input/output the simplest and most stable option for local servers.</p>
</li>
</ul>
<h3 id="heading-step-3-wire-copilot-cli-to-your-mcp-server">Step 3 – Wire Copilot CLI to Your MCP Server</h3>
<p>This is where the two systems connect. GitHub Copilot CLI supports MCP via its <code>--mcp-config</code> flag (available from version 1.3+). You point it at your <code>mcp.json</code>, and Copilot will automatically initialize the declared servers before processing your prompt.</p>
<p>Here's the basic invocation:</p>
<pre><code class="language-shell">gh copilot suggest --mcp-config ~/.config/mcp/mcp.json "why did the build break in the last commit?"
</code></pre>
<p>When you run this inside a Git repository, Copilot CLI will:</p>
<ol>
<li><p>Start the <code>mcp-server-git</code> process</p>
</li>
<li><p>Call <code>git_log</code> to retrieve recent commits</p>
</li>
<li><p>Call <code>git_diff</code> on the most recent commit</p>
</li>
<li><p>Synthesize an answer based on the actual diff output</p>
</li>
</ol>
<p>Try it yourself on a repo with a recent failing commit. The difference in response quality compared to a plain <code>gh copilot suggest</code> is immediately obvious.</p>
<p><strong>Tip: avoid retyping the flag every time.</strong> Add a shell function to your <code>.bashrc</code>/<code>.zshrc</code>:</p>
<pre><code class="language-shell">function aterm() {
  gh copilot suggest --mcp-config ~/.config/mcp/mcp.json "$@"
}
</code></pre>
<p>Now you just type:</p>
<pre><code class="language-shell">aterm "what changed between main and feature/auth?"
</code></pre>
<p>And you're running a fully context-aware, MCP-powered query from a single short command. This function name <code>aterm</code> for <em>agentic terminal</em> is what we'll use throughout the rest of this tutorial.</p>
<h3 id="heading-step-4-build-a-real-agentic-workflow">Step 4 – Build a Real Agentic Workflow</h3>
<p>Let's move beyond individual queries and build a workflow that chains multiple tool calls to complete a real developer task: <strong>diagnosing a regression</strong>.</p>
<p>Imagine you pushed a feature branch and your CI pipeline failed. You don't know exactly which change caused it. Here's how your agentic terminal handles it:</p>
<h4 id="heading-query-1-understand-what-changed">Query 1: understand what changed</h4>
<pre><code class="language-shell">aterm "summarize all commits on feature/auth that aren't on main yet"
</code></pre>
<p>Copilot calls <code>git_log</code> with branch filters, then returns a structured summary of commits unique to your branch. No copy-pasting SHAs manually.</p>
<h4 id="heading-query-2-isolate-the-diff">Query 2: isolate the diff</h4>
<pre><code class="language-shell">aterm "show me everything that changed in the auth middleware between main and feature/auth"
</code></pre>
<p>This triggers <code>git_diff</code> scoped to the path containing your middleware. Copilot returns the diff with an explanation of what each change does.</p>
<h4 id="heading-query-3-find-the-likely-culprit">Query 3: find the likely culprit</h4>
<pre><code class="language-shell">aterm "which of those changes could cause a JWT validation failure?"
</code></pre>
<p>At this point, Copilot has the diff in its context window from the previous tool calls. It reasons over the actual code changes not generic knowledge about JWT and pinpoints the likely issue.</p>
<h4 id="heading-query-4-generate-the-fix">Query 4: generate the fix</h4>
<pre><code class="language-shell">aterm "write the corrected version of that validation function"
</code></pre>
<p>Copilot generates a targeted fix based on the specific code it retrieved via MCP. You get a patch you can directly apply, not a generic code template.</p>
<p>This four-step sequence – understand, isolate, reason, fix – is a complete agentic loop. Each step is grounded in live repository data retrieved through MCP tools. The AI is not hallucinating context. Instead, it's reading your actual codebase.</p>
<h3 id="heading-step-5-extend-with-multiple-mcp-servers">Step 5 – Extend with Multiple MCP Servers</h3>
<p>One MCP server is useful. Multiple MCP servers working together is where the workflow becomes genuinely powerful. Let's add two more: <code>server-filesystem</code> and <code>server-docker</code>.</p>
<p>Install the additional servers:</p>
<pre><code class="language-shell">npm install -g @modelcontextprotocol/server-filesystem
npm install -g @modelcontextprotocol/server-docker
</code></pre>
<p>Update your <code>mcp.json</code>:</p>
<pre><code class="language-markdown">{
  "mcpServers": {
    "git": {
      "command": "mcp-server-git",
      "args": ["--repository", "."],
      "transport": "stdio"
    },
    "filesystem": {
      "command": "mcp-server-filesystem",
      "args": ["--root", "."],
      "transport": "stdio"
    },
    "docker": {
      "command": "mcp-server-docker",
      "transport": "stdio"
    }
  }
}
</code></pre>
<p>With all three servers active, your terminal can now answer cross-domain questions:</p>
<pre><code class="language-shell">aterm "my Express app container keeps restarting, check the logs and compare with what the healthcheck in my Dockerfile expects"
</code></pre>
<p>To answer this, Copilot will:</p>
<ol>
<li><p>Call <code>docker_logs</code> (server-docker) to pull the container's recent stderr output</p>
</li>
<li><p>Call <code>read_file</code> (server-filesystem) to read your <code>Dockerfile</code></p>
</li>
<li><p>Parse the <code>HEALTHCHECK</code> instruction</p>
</li>
<li><p>Cross-reference the log errors with the health endpoint path</p>
</li>
<li><p>Return a diagnosis explaining the mismatch and suggest the fix</p>
</li>
</ol>
<p>This is an <strong>agentic workflow</strong>: the model autonomously decides which tools to call, in what order, and synthesizes the results into a coherent answer. You didn't tell it to read the Dockerfile. It inferred that was necessary based on your question.</p>
<p><strong>A note on security:</strong> When running <code>server-filesystem</code>, always scope it to a specific directory using <code>--root</code>. Never point it at <code>/</code> or your home directory. Similarly, <code>server-docker</code> has access to your Docker socket run it only in trusted environments.</p>
<h2 id="heading-debugging-common-issues">Debugging Common Issues</h2>
<p><code>mcp-server-git: command not found</code></p>
<p>The npm global bin directory isn't on your <code>$PATH</code>. Fix:</p>
<pre><code class="language-shell">export PATH="\(PATH:\)(npm bin -g)"
# or for newer npm versions:
export PATH="\(PATH:\)(npm prefix -g)/bin"
</code></pre>
<p>Add this line to your <code>.bashrc</code>/<code>.zshrc</code> to persist it.</p>
<h4 id="heading-copilot-cli-doesnt-seem-to-be-using-mcp-tools">Copilot CLI doesn't seem to be using MCP tools</h4>
<p>Check your Copilot CLI version:</p>
<pre><code class="language-shell">gh copilot --version
</code></pre>
<p>MCP support requires version 1.3 or later. Update with:</p>
<pre><code class="language-shell">gh extension upgrade copilot
</code></pre>
<p>Also verify your <code>mcp.json</code> is valid JSON a trailing comma or missing bracket will silently prevent server initialization.</p>
<h4 id="heading-mcp-server-starts-but-returns-no-data">MCP server starts but returns no data</h4>
<p>Run the server manually to check for errors:</p>
<pre><code class="language-shell">mcp-server-git --repository .
</code></pre>
<p>If it exits immediately, check that you're running the command inside a valid Git repository. For <code>server-docker</code>, make sure the Docker daemon is running and your user has access to the Docker socket:</p>
<pre><code class="language-shell">sudo usermod -aG docker $USER
# Then log out and back in
</code></pre>
<h4 id="heading-responses-are-slow-with-multiple-servers">Responses are slow with multiple servers</h4>
<p>Each MCP server is a separate subprocess. Spawning several at once adds startup latency, especially on slower machines. Two optimizations:</p>
<ol>
<li><p>Only declare the servers you actually need for a given project in your <code>mcp.json</code></p>
</li>
<li><p>Use project-specific config files instead of one global config:</p>
</li>
</ol>
<pre><code class="language-shell"># project A (backend)
aterm --mcp-config ./mcp-backend.json "..."

# project B (infra)
aterm --mcp-config ./mcp-infra.json "..."
</code></pre>
<h2 id="heading-conclusion">Conclusion</h2>
<p>You've just built an agentic terminal workflow from scratch. Here's a quick recap of what you did:</p>
<ul>
<li><p>Installed and configured GitHub Copilot CLI with shell aliases for fast access</p>
</li>
<li><p>Set up MCP servers (<code>server-git</code>, <code>server-filesystem</code>, <code>server-docker</code>) and wired them through a <code>mcp.json</code> config</p>
</li>
<li><p>Created a shell function (<code>aterm</code>) that transparently passes your MCP config to every Copilot query</p>
</li>
<li><p>Built a multi-step agentic loop for diagnosing regressions using live Git data</p>
</li>
<li><p>Extended the setup with cross-domain tool orchestration across Git, filesystem, and Docker</p>
</li>
</ul>
<p>The architecture you've built here is not a demo – it's a production-ready pattern. You can extend it with any MCP-compatible server: <code>server-postgres</code> for database-aware queries, <code>server-github</code> for issue and PR context, or custom MCP servers you write yourself for your internal APIs.</p>
<p>The terminal has always been the most powerful surface in a developer's environment. With Copilot CLI and MCP, it's finally becoming an intelligent one.</p>
 ]]>
                </content:encoded>
            </item>
        
            <item>
                <title>
                    <![CDATA[ How to Fix a Failing GitHub PR: Debugging CI, Lint Errors, and Build Errors Step by Step ]]>
                </title>
                <description>
                    <![CDATA[ While many guides explain how to set up Continuous Integration pipelines, not very many show you how to debug them when things go wrong across multiple layers. This is a common experience when contrib ]]>
                </description>
                <link>https://www.freecodecamp.org/news/how-to-fix-failing-github-pr-ci-lint-build-errors/</link>
                <guid isPermaLink="false">69e9033dbca83cce6c5f0209</guid>
                
                    <category>
                        <![CDATA[ GitHub ]]>
                    </category>
                
                    <category>
                        <![CDATA[ ci-cd ]]>
                    </category>
                
                    <category>
                        <![CDATA[ debugging ]]>
                    </category>
                
                    <category>
                        <![CDATA[ Devops ]]>
                    </category>
                
                    <category>
                        <![CDATA[ markdown ]]>
                    </category>
                
                <dc:creator>
                    <![CDATA[ qacheampong ]]>
                </dc:creator>
                <pubDate>Wed, 22 Apr 2026 17:19:57 +0000</pubDate>
                <media:content url="https://cdn.hashnode.com/uploads/covers/5e1e335a7a1d3fcc59028c64/29733bad-98af-4d6e-9fb6-93d55e8f87fd.png" medium="image" />
                <content:encoded>
                    <![CDATA[ <p>While many guides explain how to set up Continuous Integration pipelines, not very many show you how to debug them when things go wrong across multiple layers.</p>
<p>This is a common experience when contributing to open source: you make a small change, open a pull request, and suddenly everything fails.</p>
<p>Not just one check, but multiple:</p>
<ul>
<li><p>Lint errors</p>
</li>
<li><p>YAML validation issues</p>
</li>
<li><p>Build failures</p>
</li>
<li><p>Deployment failures</p>
</li>
</ul>
<p>Even more confusing, you may see errors in parts of the codebase you didn’t modify.</p>
<p>In this article, you'll learn how to debug these issues step by step. The goal is not just to fix one pull request, but to understand how CI systems validate your changes.</p>
<p>This guide is based on a real debugging experience from contributing to an open source documentation project.</p>
<p>While this example comes from a documentation project, the debugging workflow applies to many repositories that use CI pipelines, linting tools, and automated builds.</p>
<h3 id="heading-table-of-contents">Table of Contents:</h3>
<ul>
<li><p><a href="#heading-understanding-the-ci-pipeline-whats-actually-happening">Understanding the CI Pipeline (What’s Actually Happening)</a></p>
</li>
<li><p><a href="#heading-how-a-ci-pipeline-processes-your-pull-request">How a CI Pipeline Processes Your Pull Request</a></p>
</li>
<li><p><a href="#heading-a-practical-debugging-workflow">A Practical Debugging Workflow</a></p>
<ul>
<li><p><a href="#heading-step-1-fix-authentication-and-permission-issues">Step 1: Fix Authentication and Permission Issues</a></p>
</li>
<li><p><a href="#heading-step-2-run-lint-checks-locally">Step 2: Run Lint Checks Locally</a></p>
</li>
<li><p><a href="#heading-step-3-fix-common-markdown-lint-errors">Step 3: Fix Common Markdown Lint Errors</a></p>
</li>
<li><p><a href="#heading-step-4-fix-yaml-inside-markdown-code-blocks">Step 4: Fix YAML Inside Markdown Code Blocks</a></p>
</li>
<li><p><a href="#heading-step-5-fix-build-errors-after-lint-passes">Step 5: Fix Build Errors After Lint Passes</a></p>
</li>
<li><p><a href="#heading-step-6-debug-cascading-ci-failures">Step 6: Debug Cascading CI Failures</a></p>
</li>
<li><p><a href="#heading-step-7-handle-git-issues-during-ci-debugging">Step 7: Handle Git Issues During CI Debugging</a></p>
</li>
</ul>
</li>
<li><p><a href="#heading-key-takeaways">Key Takeaways</a></p>
</li>
<li><p><a href="#heading-conclusion">Conclusion</a></p>
</li>
</ul>
<h3 id="heading-prerequisites"><strong>Prerequisites</strong></h3>
<p>To follow this guide, you should have:</p>
<ul>
<li><p>Basic familiarity with Git and pull requests</p>
</li>
<li><p>A GitHub account</p>
</li>
<li><p>Some exposure to CI/CD concepts (helpful but not required)</p>
</li>
</ul>
<h2 id="heading-understanding-the-ci-pipeline-whats-actually-happening"><strong>Understanding the CI Pipeline (What’s Actually Happening)</strong></h2>
<p>In many projects, you will see the term CI/CD, which stands for Continuous Integration and Continuous Deployment (or Delivery).</p>
<p>In this guide, we'll focus specifically on the CI part – that is, Continuous Integration. This refers to the automated checks that run when you push code or open a pull request. These checks validate your changes before they're merged into the main codebase.</p>
<p>CD (Continuous Deployment/Delivery), on the other hand, typically handles what happens after those checks pass, such as deploying the application.</p>
<p>Understanding this distinction is important because most of the issues we debug in this guide happen during the CI stage.</p>
<p>Most repositories run multiple automated checks when you open a pull request:</p>
<ul>
<li><p><strong>Linting tools</strong> (for example, markdownlint, yamllint) enforce formatting rules</p>
</li>
<li><p><strong>Build systems</strong> (for example, mdBook) validate structure and generate output</p>
</li>
<li><p><strong>Deployment checks</strong> (for example, Netlify) ensure that the site can be built and served</p>
</li>
<li><p><strong>Merge controllers</strong> (for example, Tide) enforce approval policies</p>
</li>
</ul>
<p>A key point to remember: CI systems validate the <strong>entire set of files in your commit,</strong> not just the lines you changed.</p>
<h2 id="heading-how-a-ci-pipeline-processes-your-pull-request"><strong>How a CI Pipeline Processes Your Pull Request</strong></h2>
<p>When you push code or open a pull request, the CI pipeline runs several checks in sequence.</p>
<p>Let’s visualize how these checks are connected in a typical CI pipeline.</p>
<img src="https://cdn.hashnode.com/uploads/covers/69d09527e466e2b762fdff59/9cecca6e-e000-46e3-a40e-cb353fc89ff8.png" alt="A CI pipeline diagram showing lint, build, and deployment steps with failure loops returning to code fixes." style="display: block;" width="2348" height="1516" loading="lazy">

<p>Figure: A simplified CI pipeline showing how linting, build, and deployment checks are executed sequentially.</p>
<p>The above diagram shows a sequential CI pipeline with feedback loops, where failures at any stage return you to fix the issue before continuing.</p>
<p>Let’s break down what this diagram shows:</p>
<ol>
<li><p>You start by pushing code or opening a pull request.</p>
</li>
<li><p>The CI pipeline begins running automated checks.</p>
</li>
<li><p>The first set of checks typically includes linting tools like markdownlint or yamllint.</p>
<ul>
<li><p>If linting fails, the pipeline stops, and you must fix formatting issues before continuing.</p>
</li>
<li><p>If linting passes, the pipeline moves to the build step (for example, mdBook in documentation projects).</p>
</li>
<li><p>If the build fails, it usually means there is a structural issue, such as duplicate entries or invalid references.</p>
</li>
</ul>
</li>
<li><p>After a successful build, deployment checks (such as Netlify previews) run.</p>
<ul>
<li>If deployment fails, the issue is often related to configuration or build output.</li>
</ul>
</li>
<li><p>If all steps pass, the pull request becomes ready for review.</p>
</li>
</ol>
<h2 id="heading-a-practical-debugging-workflow"><strong>A Practical Debugging Workflow</strong></h2>
<h3 id="heading-step-1-fix-authentication-and-permission-issues">Step 1: Fix Authentication and Permission Issues</h3>
<p>Before CI runs, your push can fail due to authentication errors.</p>
<p>Example error:</p>
<pre><code class="language-shell">refusing to allow a Personal Access Token to create or update workflow
</code></pre>
<p>This happens because GitHub requires special permissions when your commit includes files under:</p>
<pre><code class="language-shell">.github/workflows/
</code></pre>
<p>The solution is to regenerate your Personal Access Token (PAT) with:</p>
<ul>
<li><p><code>repo</code> access</p>
</li>
<li><p><code>workflow</code> permission</p>
</li>
</ul>
<h3 id="heading-step-2-run-lint-checks-locally">Step 2: Run Lint Checks Locally</h3>
<p>Relying only on CI feedback slows you down because you have to push changes and wait for the pipeline to run before seeing errors.</p>
<p>Running checks locally allows you to catch issues immediately before pushing your code.</p>
<p>In practice, you should do both:</p>
<ul>
<li><p>Run checks locally to catch errors early and reduce iteration time</p>
</li>
<li><p>Use CI as the final validation to ensure your changes meet the repository’s standards</p>
</li>
</ul>
<p>Think of local checks as your first line of defense, and CI as the final gate before your code is accepted.</p>
<p>Here's an example (Markdown linting):</p>
<pre><code class="language-shell">npm install -g markdownlint-cli2
markdownlint-cli2 docs/**/*.md
</code></pre>
<h3 id="heading-step-3-fix-common-markdown-lint-errors">Step 3: Fix Common Markdown Lint Errors</h3>
<p>Here are some common issues you may encounter:</p>
<h4 id="heading-1-non-descriptive-links">1. Non-descriptive links</h4>
<p>Non-descriptive links like "here" don't give readers any context about where the link leads. This makes documentation harder to understand and less accessible, especially for users relying on screen readers.</p>
<p>Instead of writing:</p>
<pre><code class="language-shell">[here](https://example.com)
</code></pre>
<p>Use descriptive text like:</p>
<pre><code class="language-shell">[command help documentation](https://example.com)
</code></pre>
<h4 id="heading-2-line-length-violations">2. Line length violations</h4>
<p>Many projects enforce a maximum line length (often around 80 characters) to improve readability across different devices and editors.</p>
<p>If a line is too long, you can split it into multiple lines without changing the meaning.</p>
<p>To do this, break the line at natural points such as spaces between words or after punctuation. Avoid breaking words or disrupting the sentence structure.<br>For example:</p>
<pre><code class="language-shell">This is a long sentence that should be split across multiple
lines to satisfy lint rules.
</code></pre>
<h4 id="heading-3-list-indentation-issues">3. List indentation issues</h4>
<p>List indentation errors occur when nested list items aren't aligned consistently. This can break formatting and cause linting errors.</p>
<p>To avoid this, just make sure you use consistent spacing (usually 2 spaces per level).</p>
<p>Example (incorrect):</p>
<pre><code class="language-shell">- Item 1
 - Subitem
</code></pre>
<p>Correct version:</p>
<pre><code class="language-shell">- Item 1
  - Subitem
</code></pre>
<h3 id="heading-step-4-fix-yaml-inside-markdown-code-blocks">Step 4: Fix YAML Inside Markdown Code Blocks</h3>
<p>YAML has strict formatting rules, including proper indentation, key-value structure, and consistent spacing.</p>
<p>Even when YAML appears inside a markdown code block, tools like yamllint still validate its structure.</p>
<p>Example (incorrect):</p>
<pre><code class="language-yaml">metadata:
annotations:
</code></pre>
<p>Correct version:</p>
<pre><code class="language-yaml">metadata:
  annotations:
    capi.metal3.io/unhealthy: "true"
</code></pre>
<p>In the incorrect example, <code>annotations</code> is not properly nested under <code>metadata</code>, and no key-value pair is defined.</p>
<p>In the corrected version:</p>
<ul>
<li><p><code>annotations</code> is properly indented under <code>metadata</code></p>
</li>
<li><p>a valid key-value pair is added (<code>capi.metal3.io/unhealthy: "true"</code>)</p>
</li>
</ul>
<p>This structure satisfies YAML’s requirement for proper hierarchy and formatting.</p>
<h3 id="heading-step-5-fix-build-errors-after-lint-passes">Step 5: Fix Build Errors After Lint Passes</h3>
<p>Passing lint checks doesn't guarantee that your build will succeed.</p>
<p>This is because linting focuses on syntax and formatting, while the build process validates the structure and integrity of the entire project.</p>
<p>Build failures often occur due to issues such as:</p>
<ul>
<li><p>Duplicate entries in navigation files</p>
</li>
<li><p>Missing or incorrectly referenced files</p>
</li>
<li><p>Invalid configuration settings</p>
</li>
</ul>
<p>Even if your syntax is correct, the build system ensures everything connects properly.</p>
<p>For example, in documentation projects using tools like mdBook, a duplicate entry in <code>SUMMARY.md</code> can cause the build to fail even when all files pass lint checks.</p>
<h3 id="heading-step-6-debug-cascading-ci-failures">Step 6: Debug Cascading CI Failures</h3>
<p>CI pipelines are layered. One failure can trigger multiple downstream failures.</p>
<p>For example, imagine a YAML indentation error:</p>
<pre><code class="language-shell">YAML error → build fails → deploy fails → multiple checks fail
</code></pre>
<p>To fix this:</p>
<ol>
<li><p>Identify the first failing step in the CI logs</p>
</li>
<li><p>Fix that issue</p>
</li>
<li><p>Re-run the pipeline</p>
</li>
</ol>
<p>In this example, the YAML indentation error is the root cause. Once you fix the YAML formatting, the lint check passes, which allows the build to proceed and the deployment step to succeed.</p>
<p>This is why it is important to always fix the first failure in the pipeline rather than trying to address all errors at once.</p>
<h3 id="heading-step-7-handle-git-issues-during-ci-debugging">Step 7: Handle Git Issues During CI Debugging</h3>
<p>When working with updated branches, you may encounter:</p>
<ul>
<li><p>Diverged branches</p>
</li>
<li><p>Rebase conflicts</p>
</li>
<li><p>Push rejections</p>
</li>
</ul>
<p>To resolve these issues, you typically need to update your branch using one of two approaches:</p>
<h4 id="heading-option-1-rebase-clean-history">Option 1: Rebase (clean history)</h4>
<pre><code class="language-shell">git pull --rebase
</code></pre>
<p>Rebasing rewrites your commit history so your changes appear on top of the latest version of the branch.</p>
<p>Use carefully:</p>
<ul>
<li><p>Only rebase your own branches</p>
</li>
<li><p>Avoid rebasing shared branches</p>
</li>
</ul>
<h4 id="heading-option-2-merge-safer">Option 2: Merge (safer)</h4>
<pre><code class="language-shell">git pull --no-rebase
</code></pre>
<p>Merging preserves the full commit history and is safer when working with others, but it may introduce additional merge commits.</p>
<h4 id="heading-pushing-your-changes-safely">Pushing your changes safely</h4>
<p>After updating your branch, you may need to push changes:</p>
<pre><code class="language-shell">git push --force-with-lease
</code></pre>
<p>Avoid using:</p>
<pre><code class="language-shell">git push --force
</code></pre>
<p>The <code>--force</code> option can overwrite the other contributors’ work. The <code>--force-with-lease</code> option is safer because it only pushes if the remote branch has not changed unexpectedly.</p>
<h2 id="heading-key-takeaways"><strong>Key Takeaways</strong></h2>
<ul>
<li><p>CI validates your entire commit, not just the specific lines you changed</p>
</li>
<li><p>Linting and build systems enforce different rules</p>
</li>
<li><p>YAML inside markdown must be structurally correct</p>
</li>
<li><p>Documentation builds can fail due to structural issues</p>
</li>
<li><p>Running checks locally significantly reduces debugging time</p>
</li>
</ul>
<h2 id="heading-conclusion">Conclusion</h2>
<p>Debugging a failing pull request isn't just about fixing syntax errors.</p>
<p>You also need to understand how different systems interact:</p>
<ul>
<li><p>Version control</p>
</li>
<li><p>CI pipelines</p>
</li>
<li><p>Linting tools</p>
</li>
<li><p>Build processes</p>
</li>
</ul>
<p>Once you understand how these systems work together, you can debug issues systematically instead of guessing.</p>
<p>The next time your pull request fails, you will know exactly where to start and how to fix it.</p>
<p>Debugging CI issues may feel overwhelming at first, but with a structured approach, you can turn failures into a clear path for improvement.</p>
 ]]>
                </content:encoded>
            </item>
        
            <item>
                <title>
                    <![CDATA[ How to Make Your GitHub Profile Stand Out ]]>
                </title>
                <description>
                    <![CDATA[ If you have a Github profile, you might overlook the many ways you can customize it – and that's completely understandable. After all, at its core, GitHub is a home for your code. But beyond repositor ]]>
                </description>
                <link>https://www.freecodecamp.org/news/how-to-make-your-github-profile-stand-out/</link>
                <guid isPermaLink="false">69e2cd3ffd22b8ad62900fb3</guid>
                
                    <category>
                        <![CDATA[ GitHub ]]>
                    </category>
                
                    <category>
                        <![CDATA[ Git ]]>
                    </category>
                
                    <category>
                        <![CDATA[ hiring ]]>
                    </category>
                
                    <category>
                        <![CDATA[ #developerportfolio ]]>
                    </category>
                
                <dc:creator>
                    <![CDATA[ Chinaza Chukwunweike ]]>
                </dc:creator>
                <pubDate>Sat, 18 Apr 2026 00:15:59 +0000</pubDate>
                <media:content url="https://cdn.hashnode.com/uploads/covers/5e1e335a7a1d3fcc59028c64/db5b026f-24ce-4b59-b133-9326eb8c4c06.png" medium="image" />
                <content:encoded>
                    <![CDATA[ <p>If you have a Github profile, you might overlook the many ways you can customize it – and that's completely understandable. After all, at its core, GitHub is a home for your code.</p>
<p>But beyond repositories and commits, your profile can say <em>a lot</em> about you as a developer.</p>
<p>When used intentionally, GitHub becomes more than a code hosting platform. It becomes your <strong>CV for your codebase</strong>. It tells your story, showcases your skills, and gives people a reason to trust your work.</p>
<p>In this article, we'll break down the different ways to make your GitHub profile stand out. From setting up your GitHub account to engaging storytelling for your repositories, there's lots you can do.</p>
<p>Let's get started!</p>
<h2 id="heading-table-of-contents">Table of Contents</h2>
<ul>
<li><p><a href="#heading-sign-up-for-a-github-account">Sign Up for a Github Account</a></p>
</li>
<li><p><a href="#heading-add-a-profile-image">Add a Profile Image</a></p>
</li>
<li><p><a href="#heading-add-profile-details">Add Profile Details</a></p>
</li>
<li><p><a href="#heading-add-a-profile-readme-file">Add a Profile README File</a></p>
</li>
<li><p><a href="#heading-tell-a-story-about-each-repository">Tell a Story About Each Repository</a></p>
</li>
</ul>
<h2 id="heading-step-1-sign-up-for-a-github-account">Step 1: Sign Up for a Github Account</h2>
<p>To begin, you'll need a GitHub account. If you don’t have one, you can <a href="http://GitHub.com">set one up here</a>.</p>
<p>Once you have your account set up and you're logged in, we can move on to the next step.</p>
<h2 id="heading-step-2-add-a-profile-image">Step 2: Add a Profile Image</h2>
<p>Your profile image is often the first thing people notice. It could be a professional photo of yourself, or an image or avatar that represents you or your interests</p>
<p>As long as it’s appropriate, you’re good to go.</p>
<p>To add a profile image, you'll need to:</p>
<ul>
<li><p>Open your profile menu/dashboard</p>
</li>
<li><p>Click on the image icon at the left</p>
</li>
<li><p>Click on the edit text on the image icon</p>
</li>
<li><p>Select the image to set as your profile picture</p>
</li>
<li><p>Click the "Set new profile picture" button</p>
</li>
</ul>
<p>So, you should have something like this:</p>
<img src="https://cloudmate-test.s3.us-east-1.amazonaws.com/uploads/covers/69721aa76d7c64defcdf1b2c/b05395a9-3f7a-44ce-89a8-2e7759f06ad7.png" alt="Image showing the new Profile image added" style="display: block;" width="600" height="400" loading="lazy">

<p><strong>GitHub link to this page:</strong> <a href="https://github.com/settings/profile">https://github.com/settings/profile</a></p>
<p>And there you have it, your GitHub profile image is set.</p>
<p>On to the next one…</p>
<h2 id="heading-step-3-add-profile-details">Step 3: Add Profile Details</h2>
<p>This step is all about credibility and discoverability.</p>
<p>At the center of your profile settings you'll see fields like email, location, social media links and so on. We'll be adding those details so you can take advantage of the discoverability it lends to your profile.</p>
<img src="https://cloudmate-test.s3.us-east-1.amazonaws.com/uploads/covers/69721aa76d7c64defcdf1b2c/d3ca4a77-e3a6-4cd5-a139-3059b0dcc802.png" alt="Image showing public profile settings tab" style="display: block;" width="600" height="400" loading="lazy">

<p><strong>GitHub link to this page:</strong> <a href="https://github.com/settings/profile">https://github.com/settings/profile</a></p>
<p>For this step, you'll want to add as much detail as possible (apart from your home address – I think we both know why).</p>
<p>For the location, you can just put in your city or country so others have a general idea of where you are in the world.</p>
<h2 id="heading-step-4-add-a-profile-readme-file">Step 4: Add a Profile README File</h2>
<p>This is where you introduce yourself properly and tell your story.</p>
<p>A <strong>Profile README</strong> is a special repository named exactly the same as your GitHub username. Your README file appears directly on your profile page.</p>
<p>The READme should answer the following questions:</p>
<ul>
<li><p>Who are you?</p>
</li>
<li><p>What are your project highlights?</p>
</li>
<li><p>What are you currently working on or learning?</p>
</li>
<li><p>Your hobbies or interests (optional)</p>
</li>
</ul>
<p>While answering these questions, you should aim to keep it minimal and yet interesting. You don't want to overwhelm the visitor.</p>
<p>Here's how to create your README:</p>
<ul>
<li><p>Click New repository</p>
</li>
<li><p>Name the repository exactly the same as your GitHub username</p>
</li>
<li><p>Check “Add a README file”</p>
</li>
<li><p>Make sure the repository is public</p>
</li>
<li><p>Click Create repository</p>
</li>
</ul>
<p>Profile README file setup:</p>
<img src="https://cloudmate-test.s3.us-east-1.amazonaws.com/uploads/covers/69721aa76d7c64defcdf1b2c/c4ecd23d-6f0b-41d9-a16c-915cea2e9096.png" alt="Image showing profile README file being created" style="display: block;" width="600" height="400" loading="lazy">

<p><strong>GitHub link to this page:</strong> <a href="https://github.com/new">https://github.com/new</a></p>
<p>So if you answered the questions listed above, your README file should look something like this:</p>
<img src="https://cloudmate-test.s3.us-east-1.amazonaws.com/uploads/covers/69721aa76d7c64defcdf1b2c/a8685c0e-8f97-49b4-b7fc-4efa541acc3b.png" alt="Image showing Profile README section already created" style="display: block;" width="600" height="400" loading="lazy">

<p><strong>GitHub link to this page:</strong> <a href="https://github.com/chinazachisom/chinazachisom">https://github.com/chinazachisom/chinazachisom</a></p>
<p>It should also be showing directly on your GitHub profile like below:</p>
<img src="https://cdn.hashnode.com/uploads/covers/69721aa76d7c64defcdf1b2c/7ed8961e-17aa-4b35-999a-b871f3c27905.png" alt="Github Profile Showing the Newly Added README file" style="display: block;" width="2978" height="1708" loading="lazy">

<p><strong>GitHub link to this page:</strong> <a href="https://github.com/chinazachisom">https://github.com/chinazachisom</a></p>
<h2 id="heading-step-5-tell-a-story-about-each-repository">Step 5: Tell a Story About Each Repository</h2>
<p>Now, this is where you can tell a story about each of your repositories using a README file.</p>
<p><strong>NB: Each repository should have its own separate README file.</strong></p>
<p>What to include in a repository README:</p>
<ul>
<li><p>Project title</p>
</li>
<li><p>What the project is</p>
</li>
<li><p>The purpose (the “why”)</p>
</li>
<li><p>Key features</p>
</li>
<li><p>Challenges you faced and how you solved them</p>
</li>
<li><p>Setup or usage instructions (or a live link if hosted)</p>
</li>
<li><p>Technical concepts used (e.g., throttling, caching, lazy loading) <em>(optional)</em></p>
</li>
<li><p>Images or video demos</p>
</li>
</ul>
<p>You may also include badges, charts, contribution graphs or other visual enhancements that help highlight project quality, activity and impact.</p>
<p>With the above structure, you can tell the stories behind your projects, show your problem-solving skills, and make your work easier to understand and evaluate.</p>
<p><strong>Repository README File Sample:</strong></p>
<img src="https://cloudmate-test.s3.us-east-1.amazonaws.com/uploads/covers/69721aa76d7c64defcdf1b2c/63bc276b-798b-4a9e-a094-93330e3eeab0.png" alt="Image showing the README file for the new repository" style="display: block;" width="600" height="400" loading="lazy">

<p><strong>GitHub link to this page:</strong> <a href="https://github.com/chinazachisom/Artsy">https://github.com/chinazachisom/Artsy</a></p>
<h2 id="heading-conclusion">Conclusion</h2>
<p>Your Github Profile is more than just a storage space for your codebase. It's your developer Identity as well.</p>
<p>Following these basic steps can help turn your Github into a portfolio infused with your personal brand. It makes your GitHub Profile stand out, which can help open doors for more opportunities.</p>
<p>Treat it like a CV for your code and let your work speak for you.</p>
<h3 id="heading-about-the-author">About the Author</h3>
<p>Hi there! I'm Chinaza Chukwunweike, a Software Engineer passionate about building robust, scalable systems that make a real world impact. I'm also an advocate for continuous learning and improvement.</p>
<p>If you found this useful, please share it! And follow me for more Software Engineering tips, AI learning strategies, and productivity frameworks.</p>
 ]]>
                </content:encoded>
            </item>
        
            <item>
                <title>
                    <![CDATA[ What Happened When I Replaced Copilot with Claude Code for 2 Weeks ]]>
                </title>
                <description>
                    <![CDATA[ GitHub Copilot costs $10/month, and I'd been using it for two years without thinking twice. But when Claude Code launched, I got curious. What if I just... switched? I didn't want to just add Claude C ]]>
                </description>
                <link>https://www.freecodecamp.org/news/what-happened-when-i-replaced-copilot-with-claude-code-for-2-weeks/</link>
                <guid isPermaLink="false">69c6d07e7cf2706510370b13</guid>
                
                    <category>
                        <![CDATA[ AI ]]>
                    </category>
                
                    <category>
                        <![CDATA[ claude.ai ]]>
                    </category>
                
                    <category>
                        <![CDATA[ copilot ]]>
                    </category>
                
                    <category>
                        <![CDATA[ GitHub ]]>
                    </category>
                
                    <category>
                        <![CDATA[ Programming Tips ]]>
                    </category>
                
                <dc:creator>
                    <![CDATA[ Balajee Asish Brahmandam ]]>
                </dc:creator>
                <pubDate>Fri, 27 Mar 2026 18:46:22 +0000</pubDate>
                <media:content url="https://cdn.hashnode.com/uploads/covers/5e1e335a7a1d3fcc59028c64/b4f5a663-3ef6-4fcb-a08c-1c0ff36c495d.png" medium="image" />
                <content:encoded>
                    <![CDATA[ <p>GitHub Copilot costs $10/month, and I'd been using it for two years without thinking twice. But when Claude Code launched, I got curious. What if I just... switched?</p>
<p>I didn't want to just add Claude Code to my stack. I actually wanted to replace Copilot entirely for two weeks. I kept everything else the same – same editor, same projects, same workflow. I just swapped the autocomplete suggestion tool.</p>
<p>Here's what broke, what improved, and whether I went back.</p>
<h2 id="heading-table-of-contents">Table of Contents</h2>
<ul>
<li><p><a href="#heading-the-setup">The Setup</a></p>
</li>
<li><p><a href="#heading-what-worked-better">What Worked Better</a></p>
</li>
<li><p><a href="#heading-what-broke-or-slowed-things-down">What Broke (Or Slowed Things Down)</a></p>
</li>
<li><p><a href="#heading-the-first-week-vs-the-second-week">The First Week vs The Second Week</a></p>
</li>
<li><p><a href="#heading-why-i-went-back">Why I Went Back</a></p>
</li>
<li><p><a href="#heading-the-honest-verdict">The Honest Verdict</a></p>
</li>
<li><p><a href="#heading-what-i-actually-use-now">What I Actually Use Now</a></p>
</li>
<li><p><a href="#heading-copilot-vs-claude-code-the-breakdown">Copilot vs Claude Code — The Breakdown</a></p>
</li>
<li><p><a href="#heading-a-word-on-developer-experience">A Word on Developer Experience</a></p>
</li>
<li><p><a href="#heading-what-would-make-me-switch">What Would Make Me Switch</a></p>
</li>
<li><p><a href="#heading-final-thoughts">Final Thoughts</a></p>
</li>
</ul>
<h2 id="heading-the-setup">The Setup</h2>
<p><strong>Environment:</strong></p>
<ul>
<li><p>Python 3.12 for backend work (Django REST framework specifically)</p>
</li>
<li><p>React/TypeScript for frontend</p>
</li>
<li><p>VSCode as my editor</p>
</li>
<li><p>A mid-sized project with about 15k lines of code across backend and frontend</p>
</li>
<li><p>Two weeks, normal workload (roughly 30-40 hours of coding)</p>
</li>
<li><p>Working on features I'd normally tackle: adding endpoints, debugging issues, writing tests</p>
</li>
</ul>
<p><strong>What I did:</strong></p>
<ul>
<li><p>Disabled GitHub Copilot completely. Uninstalled the extension.</p>
</li>
<li><p>Set up Claude Code (via their CLI and VSCode integration).</p>
</li>
<li><p>Kept everything else identical: same repos, same Git flow, same daily work.</p>
</li>
<li><p>Tracked time on each task to see if there was a real difference.</p>
</li>
</ul>
<p><strong>Ground rules:</strong></p>
<ul>
<li><p>I couldn't use Copilot as a fallback. This was an honest comparison.</p>
</li>
<li><p>I logged every time I got frustrated or felt like Claude Code was slowing me down.</p>
</li>
<li><p>I kept track of bugs I caught vs. bugs I missed.</p>
</li>
</ul>
<p>The goal: Does Claude Code work as a day-to-day replacement for Copilot, or does it force me back?</p>
<h2 id="heading-what-worked-better">What Worked Better</h2>
<h3 id="heading-accuracy">Accuracy</h3>
<p>Copilot sometimes suggests things that are close but not quite right. It might finish a regex pattern 80% correctly, and I have to tweak it. It happens maybe 20% of the time.</p>
<p>Claude Code was more accurate. In the first week, I noticed fewer "close but wrong" suggestions. When I typed a function signature, Claude got the implementation right more often than Copilot did.</p>
<p>One example: I was writing a utility to parse JSON and handle errors. Copilot suggested:</p>
<pre><code class="language-python">def parse_json(data):
 try:
 return json.loads(data)
 except:
 return None
</code></pre>
<p>That's sloppy. It catches all exceptions and silently fails.</p>
<p>Claude Code suggested:</p>
<pre><code class="language-python">def parse_json(data):
 try:
 return json.loads(data)
 except json.JSONDecodeError as e:
 logging.error(f"Failed to parse JSON: {e}")
 return None
 except Exception as e:
 logging.error(f"Unexpected error: {e}")
 raise
</code></pre>
<p>Better error handling. More production-ready. That's a real difference.</p>
<p>I estimate Claude Code's suggestions were "immediately usable" about 85% of the time. Copilot was more like 70%.</p>
<h3 id="heading-understanding-context">Understanding Context</h3>
<p>Claude Code seems to understand your project better than Copilot. When I opened a file with Claude Code context, it knew:</p>
<ul>
<li><p>My project's naming conventions (I use <code>fetch_</code> for async functions, <code>get_</code> for sync).</p>
</li>
<li><p>My error handling style.</p>
</li>
<li><p>What libraries I was using.</p>
</li>
</ul>
<p>Copilot sometimes forgot these patterns or suggested things using the wrong library. Claude Code was more consistent.</p>
<p>One morning I was adding a new endpoint to an existing API. I typed the route signature:</p>
<pre><code class="language-python">@app.post("/api/users")
async def create_user(data: UserPayload):
</code></pre>
<p>Copilot might suggest:</p>
<pre><code class="language-python"> response = requests.post(...)
</code></pre>
<p>(Wrong! That's sync. This function is async.)</p>
<p>Claude Code suggested:</p>
<pre><code class="language-python"> async with httpx.AsyncClient() as client:
 response = await client.post(...)
</code></pre>
<p>It remembered that the entire codebase uses async/await and httpx for async calls. That's attention to detail.</p>
<h3 id="heading-reasoning-about-requirements">Reasoning About Requirements</h3>
<p>Sometimes Copilot just completes code. It doesn't think about whether it makes sense.</p>
<p>Claude Code seemed to reason about whether the suggestion was actually what you wanted. A few times, when I was writing ambiguous code, Claude Code offered a clarifying suggestion instead of just finishing it.</p>
<p>Example: I started a function for sorting users:</p>
<pre><code class="language-python">def sort_users(users):
</code></pre>
<p>Copilot would auto-complete with some sorting logic, but I'd have to check if it was what I meant.</p>
<p>Claude Code would sometimes suggest:</p>
<pre><code class="language-python">def sort_users(users, key="created_at", reverse=False):
</code></pre>
<p>It was thinking: "Sorting is ambiguous. What key? What order?" It was right more often than not.</p>
<h2 id="heading-what-broke-or-slowed-things-down">What Broke (Or Slowed Things Down)</h2>
<h3 id="heading-response-time">Response Time</h3>
<p>This was the biggest issue. Copilot is instant. I type <code>def get_</code> and it finishes before I can blink. It's autocomplete, and autocomplete needs to be fast. The latency is maybe 100-200ms.</p>
<p>Claude Code has a noticeable delay. Maybe 1-2 seconds before suggestions appear. On day one, that felt fine – I had time to think. By day two, I was annoyed. By day three, I was genuinely frustrated.</p>
<p>Over a day of coding, that adds up. If you're typing 20 functions and each one has a 2-second delay, that's 40 seconds of just waiting. It doesn't sound like much, but it breaks flow. Flow is where the good coding happens.</p>
<p>By day three, I was getting frustrated. I'd type faster than Claude Code could suggest, which meant I'd often just finish the code myself. The second a suggestion appeared, I'd already moved on. Defeating the purpose.</p>
<p>I tested this by tracking time. Same function, same complexity:</p>
<ul>
<li><p><strong>With Copilot:</strong> 3 minutes (including auto-complete time)</p>
</li>
<li><p><strong>With Claude Code:</strong> 5 minutes (waiting for suggestions + finishing manually)</p>
</li>
</ul>
<p>The delay isn't theoretical. It's real and measurable.</p>
<p><strong>The truth:</strong> Copilot is an autocomplete tool. It needs sub-second latency. Claude Code, being more powerful, is inherently slower. That's a fundamental tradeoff. You can't have both "instant" and "smart." Choose one.</p>
<h3 id="heading-no-inline-acceptance">No Inline Acceptance</h3>
<p>With Copilot, I press Tab to accept. It's in my muscle memory. Tab = accept.</p>
<p>Claude Code doesn't work exactly the same way. I had to click or use a different keyboard shortcut. Small thing, but it broke my rhythm constantly. I'd write code, see a suggestion, and instinctively press Tab. Nothing would happen. Then I'd remember: "Oh right, it's a different tool."</p>
<p>After two weeks, I never fully got used to it.</p>
<h3 id="heading-disconnected-from-flow">Disconnected From Flow</h3>
<p>Copilot is so embedded in the editor that I don't think about it. It's just there, like spellcheck. Claude Code feels like a separate tool I'm using, which means I'm more aware of it. That sounds like a good thing, but it's actually more cognitively expensive.</p>
<p>I wanted to type and have suggestions appear. Instead, I felt like I was using a tool. There's a difference. It's the same difference between walking and thinking about walking. When you're thinking about your walking mechanics, you walk worse.</p>
<p>This affected my productivity more than I expected. On day three, I found myself just typing manually instead of waiting for suggestions. It wasn't a conscious decision. I'd just start typing and then remember "oh, the suggestion came in." By then I'd already finished half the function myself.</p>
<h3 id="heading-limited-to-the-file">Limited to the File</h3>
<p>Copilot understands your entire project. It knows what's in other files, what libraries you import, what conventions you follow. If I'm importing a utility function that doesn't exist yet, Copilot knows to suggest the import with the path I'd use.</p>
<p>Claude Code seemed more limited to the current file. Sometimes it would suggest imports that weren't already in the file, or use patterns different from the rest of my codebase. Not often, but enough to notice. On one occasion, it suggested a database query pattern that was different from my whole codebase. It would've worked, but it would've been inconsistent.</p>
<p>This is less of a limitation and more of a design difference. Claude Code is built for depth on individual files, not breadth across a project.</p>
<h2 id="heading-the-first-week-vs-the-second-week">The First Week vs The Second Week</h2>
<p><strong>Week 1:</strong> I was excited. Claude Code felt smarter. I noticed the accuracy advantage. But the latency was starting to annoy me.</p>
<p><strong>Week 2:</strong> The novelty wore off. The latency was more annoying. I was missing Copilot's speed. I found myself disabling Claude Code's suggestions and typing manually more often, which defeated the purpose. "If I'm typing it all manually anyway, why switch?"</p>
<p>By day 10, I was typing code faster with Claude Code disabled than with it enabled. That's when I knew it wasn't working for me.</p>
<h2 id="heading-why-i-went-back">Why I Went Back</h2>
<p>On day 14, I re-enabled Copilot.</p>
<p>The first thing I noticed: speed. Code was completing again instantly. My rhythm came back. I hit Tab, it accepted, I moved on. That's the entire appeal of Copilot-it's frictionless.</p>
<p>I also realized how much I'd been manually typing. On days 10-14, I was writing more code by hand because the suggestions felt too slow to be worth waiting for. Without realizing it, I'd completely stopped using Claude Code's suggestions. I was just typing. That's the worst of both worlds: no AI help and the cognitive burden of being aware you're using a tool that's not helping.</p>
<p>Was I sacrificing accuracy? A little. But I'm accurate enough that I catch mistakes in review. For day-to-day, Copilot is fine.</p>
<p>The second thing: it just works. No weird setup, no integration issues. It's part of VSCode. It's always there.</p>
<p>By day 15, I was back to normal productivity, maybe even higher because the flow was better.</p>
<h2 id="heading-the-honest-verdict">The Honest Verdict</h2>
<p>Claude Code isn't a Copilot replacement. It's not worse. It's different. It's like comparing a calculator to a calculator app on your phone. One is designed for speed and muscle memory. One is designed to be a full computer in your pocket. They're not competitors.</p>
<p>If I'd tried Claude Code expecting it to be better at debugging, I would've been happy. I was trying it expecting it to replace my autocomplete, which is where it falls flat.</p>
<p>The experiment was valuable, though. It taught me that:</p>
<ol>
<li><p>Latency matters more than I expected. A 2-second delay breaks flow.</p>
</li>
<li><p>Familiarity matters. Tab to accept is burned into my muscle memory.</p>
</li>
<li><p>Tool stacking works. Claude Code is great for debugging. Copilot is great for autocomplete. Together they're better than either alone.</p>
</li>
</ol>
<h2 id="heading-what-i-actually-use-now">What I Actually Use Now</h2>
<p>I didn't abandon Claude Code. I just changed how I use it.</p>
<ul>
<li><p><strong>Claude Code:</strong> For debugging, analysis, and big changes. "Why is this function slow?" "Refactor this for readability." I invoke it deliberately when I need thinking, not continuous autocomplete.</p>
</li>
<li><p><strong>Copilot:</strong> For routine coding. Finishing functions, auto-completing imports, normal flow.</p>
</li>
</ul>
<p>That's the working solution. Claude Code is powerful, but it's not a Copilot replacement for daily work. It's a different tool for a different use case.</p>
<h2 id="heading-copilot-vs-claude-code-the-breakdown">Copilot vs Claude Code: The Breakdown</h2>
<p><strong>Copilot is better for:</strong></p>
<ul>
<li><p>Pure autocomplete speed</p>
</li>
<li><p>Routine, well-understood coding</p>
</li>
<li><p>Low friction, high flow state</p>
</li>
<li><p>Simple suggestions</p>
</li>
</ul>
<p><strong>Claude Code is better for:</strong></p>
<ul>
<li><p>Complex suggestions that require reasoning</p>
</li>
<li><p>Debugging and analysis</p>
</li>
<li><p>Understanding intent (not just completing code)</p>
</li>
<li><p>Asking questions about code you've written</p>
</li>
</ul>
<p>If you're a Copilot user thinking about switching, don't do it as a straight replacement. Claude Code isn't faster. It's smarter, but slower, and for day-to-day autocomplete, faster wins.</p>
<p>Try using both. Use Copilot for normal coding, Claude Code for debugging and complex changes. If you only want to pay for one, stick with Copilot. It's cheaper, it's faster, and it does the job.</p>
<p>If you're a heavy debugger and you spend a lot of time analyzing code, Claude Code might be worth it. But as a Copilot replacement? No.</p>
<h2 id="heading-a-word-on-developer-experience">A Word on Developer Experience</h2>
<p>What surprised me wasn't just the latency. It was how much I missed the seamlessness of Copilot. With Copilot, I don't think about it. It's like breathing-automatic. I type, it suggests, I accept or reject, I move on.</p>
<p>With Claude Code, I was constantly aware I was using a tool. I'd finish typing before the suggestion appeared. I'd have to remember the keyboard shortcut. I'd have to context-switch to look at the suggestion.</p>
<p>That awareness is exhausting. It's why flow state is so important to programming. The best tools get out of your way. Copilot gets out of the way. Claude Code, for autocomplete purposes, doesn't.</p>
<p>Developer experience isn't a nice-to-have. It's core to productivity. A tool that's 10% smarter but 50% more annoying is worse, not better.</p>
<h2 id="heading-what-would-make-me-switch">What Would Make Me Switch</h2>
<ul>
<li><p>Claude Code needs to get faster. Sub-second latency for suggestions.</p>
</li>
<li><p>It needs better editor integration. Tab to accept, like Copilot.</p>
</li>
<li><p>It needs to understand the full project, not just the current file.</p>
</li>
</ul>
<p>Once those three things happen, it'd be competitive. Until then, Copilot is still the better choice for daily coding work.</p>
<h2 id="heading-final-thoughts">Final Thoughts</h2>
<p>This experiment taught me something: better isn't always better. Claude Code is arguably smarter than Copilot. But Copilot is more efficient. For autocomplete, efficiency matters more than intelligence.</p>
<p>It's like comparing a sports car to a Jeep. The sports car is faster on a highway. The Jeep is better on a mountain trail. Neither is "better." They're different. Copilot is trying to predict the next line of code fast. Claude Code is trying to understand your code deeply. They're solving different problems.</p>
<p>I went back to Copilot not because Claude Code is bad. It's actually impressive. But it's a different category of tool. Using it for autocomplete is like using a hammer when you need a screwdriver. The hammer might be fancier, but the screwdriver does the job.</p>
<p>What surprised me most was how much latency matters. I didn't expect a 2-second delay to be that noticeable. But when you're in the zone, typing code, and the autocomplete lags, it completely breaks your flow. It's not about the absolute time. It's about the interruption.</p>
<p>Don't take my word for it though. Run your own two-week experiment. Pick a tool, commit to it, and see what happens. Track your productivity. Track your frustration. The best tool is the one you'll actually use. And you can only find that out by using it.</p>
<h2 id="heading-whats-next">What's Next?</h2>
<p>If you found this useful, I write about Docker, AI tools, and developer workflows every week. I'm Balajee Asish - Docker Captain, freeCodeCamp contributor, and currently building my way through the AI tools space one project at a time.</p>
<p>Got questions or built something similar? Drop a comment below or find me on <a href="https://github.com/balajee-asish">GitHub</a> and <a href="https://linkedin.com/in/balajee-asish">LinkedIn</a>.</p>
<p>Happy building.</p>
 ]]>
                </content:encoded>
            </item>
        
            <item>
                <title>
                    <![CDATA[ OSS Pull Request Therapy: Learning to Enjoy Code Reviews with npmx ]]>
                </title>
                <description>
                    <![CDATA[ For years, I thought Open Source Software (OSS) just wasn’t for me. I had no plans to join any OSS communities on top of my existing developer community obligations. Curious about the hype I saw on Bl ]]>
                </description>
                <link>https://www.freecodecamp.org/news/learning-to-enjoy-code-reviews-with-npmx/</link>
                <guid isPermaLink="false">69a6f99556428acc6fef7fbc</guid>
                
                    <category>
                        <![CDATA[ Programming Blogs ]]>
                    </category>
                
                    <category>
                        <![CDATA[ Git ]]>
                    </category>
                
                    <category>
                        <![CDATA[ GitHub ]]>
                    </category>
                
                    <category>
                        <![CDATA[ Open Source ]]>
                    </category>
                
                    <category>
                        <![CDATA[ open source ]]>
                    </category>
                
                <dc:creator>
                    <![CDATA[ Abbey Perini ]]>
                </dc:creator>
                <pubDate>Tue, 03 Mar 2026 15:09:09 +0000</pubDate>
                <media:content url="https://cdn.hashnode.com/uploads/covers/5e1e335a7a1d3fcc59028c64/a7279107-48a9-429b-8c51-dba2b8fe2b52.png" medium="image" />
                <content:encoded>
                    <![CDATA[ <p>For years, I thought Open Source Software (OSS) just wasn’t for me. I had no plans to join any OSS communities on top of my existing developer community obligations.</p>
<p>Curious about the hype I saw on <a href="https://bsky.app/">Bluesky</a>, I recently joined the <a href="https://npmx.dev/">npmx</a> Discord server on a whim. My journey from lurker to contributor taught me a lot about OSS and gave me new confidence going into code reviews.</p>
<p>In this article, I’ll walk you through my journey to give you a little insight into the process of getting involved in Open Source.</p>
<h3 id="heading-heres-what-ill-cover">Here’s what I’ll cover:</h3>
<ul>
<li><a href="#heading-my-struggles-with-pull-requests">My Struggles with Pull Requests</a></li>
<li><a href="#heading-my-former-view-of-oss">My Former View of OSS</a><ul>
<li><a href="#heading-the-basics-of-oss">The Basics of OSS</a></li>
<li><a href="#heading-the-dark-side-of-oss">The Dark Side of OSS</a></li>
</ul>
</li>
<li><a href="#heading-getting-started-with-npmx">Getting Started with npmx</a></li>
<li><a href="#heading-the-not-so-perfect-pr">The Not So Perfect PR</a></li>
<li><a href="#heading-collaboration-over-perfection">Collaboration Over Perfection</a></li>
<li><a href="#heading-my-current-view-of-oss">My Current View of OSS</a></li>
<li><a href="#heading-tips-for-pr-authors-and-reviewers">Tips for PR Authors and Reviewers</a></li>
<li><a href="#heading-conclusion">Conclusion</a></li>
</ul>
<h2 id="heading-my-struggles-with-pull-requests">My Struggles with Pull Requests</h2>
<p>I’ll admit, I’ve always had a hard time with code reviews. I can be quite the perfectionist. I’ll entertain every nitpick and only hear the criticism.</p>
<p>If reviews go on for days, I easily get overwhelmed. I enjoy pairing and co-working. I want to enjoy Pull Request (PRs), but addressing PR comments takes a lot out of me.</p>
<img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1771264593124/b5674020-6b0d-4ad2-bb92-921d05ebecc7.png" alt="Me looking at the bugs that my colleagues pointed out in my pull request Patrick Star from Spongebob looking absolutely horrified and staring at a computer" style="display: block;" width="623" height="566" loading="lazy">

<p>Some of my struggle is a need for <a href="https://askjan.org/disabilities/Attention-Deficit-Hyperactivity-Disorder-AD-HD.cfm#spy-scroll-heading-2">accommodations</a> that I rarely get. I also have plenty of lived experience with how hostile code reviews can become (even in a professional setting). Finally, there’s how I was introduced to PR reviews.</p>
<p>Outside of work, I had only ever experienced perfunctory PRs – I’d receive at most one suggestion, but usually just got a “LGTM” (Looks Good to Me) comment. Professionally, I went from no code reviews to incredibly detailed code reviews basically overnight. I still feel like I’m playing catch up.</p>
<p>On the one hand, thinking deeply about every suggestion has made me a better developer. I thrive in collaborative environments with thoughtful code reviews. Developers who have worked with me have told me that they benefit from answering all my “why?” questions.</p>
<p>On the other hand, I demand compliments, gifs, and video calls from my reviewers. I don’t do well with a bombardment of vague comments on my PRs. I’ve spent a lot of time documenting code guidelines and review processes that other people seem to understand and remember much more easily than I do.</p>
<p>Developer communities have helped me navigate all of this. Community is a priceless resource for career changers and new grads. When everyone shares their experience, the uninitiated learn about how things could be and what kinds of things aren’t normal (like very hostile code reviews).</p>
<h2 id="heading-my-former-view-of-oss">My Former View of OSS</h2>
<p>When I’ve talked and written about developer community, I’ve recommended online networking communities, going to meetups, tech conferences, social media, writing, and posting your writing online. The one thing I haven’t written about? OSS.</p>
<p>My first real introduction to OSS was through the online networking group <a href="https://virtualcoffee.io/">Virtual Coffee</a>. By the end of my first <a href="https://hacktoberfest.com/">Hacktoberfest</a>, I knew the basics.</p>
<h3 id="heading-the-basics-of-oss">The Basics of OSS</h3>
<ul>
<li>Find a project that interests you.</li>
<li>Check the Contributing Guide.</li>
<li>Claim an issue.</li>
<li>Following the Contributing Guide, make a fork, write the code, and open a PR.</li>
<li>The maintainer merges it.</li>
<li>You did it! That’s OSS.</li>
</ul>
<h3 id="heading-the-dark-side-of-oss">The Dark Side of OSS</h3>
<p>Over time, I couldn’t help but see the “dark side” of OSS – maintainers <a href="https://github.com/zloirock/core-js/blob/master/docs/2023-02-14-so-whats-next.md">burning out</a>, <a href="https://github.com/tailwindlabs/tailwindcss.com/pull/2388#issuecomment-3717222957">friction between users and maintainers</a>, corporations suddenly trying to assert control over OSS (for example, <a href="https://www.cmswire.com/digital-experience/whats-with-the-open-source-drama-between-wordpress-and-wp-engine/">Wordpress</a>, <a href="https://dev.to/cseeman/what-just-happened-to-rubygems-31n9">Ruby</a>), and the thankless, frustrating job of maintaining a package that everyone uses but no one wants to pay for.</p>
<img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1771191134959/871a6a8d-85ea-402a-950e-ec25d4738859.png" alt="A large structure made out of building blocks labelled All Modern Digital Infrastructure. One tiny, integral block is labelled A project some random person in Nebraska has been thanklessly maintaining since 2003" style="display: block;" width="385" height="489" loading="lazy">

<p>I have to be honest: I had begun to think of open source maintainers as <a href="https://www.youtube.com/watch?v=mm8R3u_b0yU">Roz from Monsters Inc.</a> – justifiably fed up with the extra work dumped on them by unappreciative people.</p>
<img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1770053555027/4f38e415-3100-4737-af1c-947725c60b23.png" alt="A slug person wearing a cardigan, holding a pencil and clipboard with the Monsters Inc. logo. She's wearing glasses and lipstick. Her grey hair is styled straight up, she has a mole on her bottom lip. She currently looks disgusted." style="display: block;" width="604" height="512" loading="lazy">

<p>Meeting maintainers in-person didn’t contradict my view. Every single one had a story about <a href="https://medium.com/@sohail_saifii/the-open-source-maintainer-burnout-crisis-nobodys-fixing-5cf4b459a72b">burnout and lack of funding</a>. I started to assume that anyone excited about OSS just hadn’t been in it long enough</p>
<p>…so my friends were quite surprised when I suddenly announced that I had joined the OSS project <a href="https://npmx.dev/">npmx</a>.</p>
<h2 id="heading-getting-started-with-npmx">Getting Started with npmx</h2>
<p>It wasn’t the first mention of the npmx project that interested me. It wasn’t the second. It was a <a href="https://bsky.app/profile/erus.dev/post/3mdicpnmijk2o">meme</a>. I’ve known <a href="https://roe.dev/">Daniel Roe</a> long enough to know that he is brilliant. I like learning from people who are smarter than I am.</p>
<p>I reached out to <a href="https://bsky.app/profile/patak.dev">Patak</a>, and got an invite to the <a href="https://chat.npmx.dev/">npmx Discord server</a>. I was amazed by what I saw: a rapidly growing, excited, and inclusive community. I realized that I had only ever contributed to communities with at most a handful of people. My view of OSS immediately changed.</p>
<p>This was it. I was finally going to have fun doing PRs.</p>
<p>So I hopped into the <a href="https://github.com/npmx-dev/npmx.dev">npmx GitHub repository</a> and tried to get my bearings. Very quickly, I was overwhelmed. The project moves <em>so fast.</em> I tried to do step 3 – claim a ticket. As far as I could tell, all the tickets were being claimed in Discord before or as they were being written.</p>
<p><a href="https://bsky.app/profile/jonathanyeong.com">Jono</a> kindly welcomed me into his fork for working on the blog page, but I ran into frustrating and weird issues with running the repository (repo) locally and the pre-commit hooks. Multiple people tried to help me debug and were just as stumped as I was.</p>
<p>The next day, <a href="https://bsky.app/profile/whitep4nth3r.com">Salma</a> arrived. The day after, she was in charge of outreach, and asked me to write a blog. Then life got in the way. I couldn’t keep my promise to <a href="https://www.software.com/devops-guides/context-switching">context switch</a> into a feature branch in a new repo. I felt like my only contribution was going to be a single line change on the blog page and a blog.</p>
<p>It didn’t help that I wasn’t happy with the blog I had started writing. I gave up on keeping up and lurked in the Discord channels. I chimed in on a few conversations, and offered to help with things like failing accessibility tests.</p>
<img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1771190012891/ac34a318-46f7-45d8-90c3-10837627ad17.png" alt="check @AbbeyPerini's reaction here, if we manage to set an example on how good an app can be with good #a11y, great #perf, and a good #test story, listening to the #e18e folks on keeping deps clean, the npmx repo will be a great learning resource for folks learning how to build websites Salma If anything I made it MORE accessible with a this react Abbey Perini let me run it locally and see if I can spot something with 3 purple heart reacts God it's nice to look at a repo where a11y wasn't an afterthought 6 100 reacts" style="display: block;" width="1008" height="708" loading="lazy">

<p>Four days later, the project was officially two weeks old. The maintainers announced a mandatory week of vacation – community members experienced with burnout had seen the writing on the wall. Vacation would start in 10 days, so that’s basically how long I had to get a contribution in before the alpha release.</p>
<h2 id="heading-the-not-so-perfect-pr">The Not So Perfect PR</h2>
<p>An hour later, I finally saw it – my chance to contribute code. <a href="https://bsky.app/profile/alexdln.com">Alex</a> needed <a href="https://github.com/npmx-dev/npmx.dev/issues/1028">a toggle re-written as a checkbox</a>. It was my time to shine. I commented on the ticket to claim it as soon as it was written. I slapped up a draft PR to show I was working on it. Predictably, my focus was once again pulled away from the repo.</p>
<p>A couple days later, <a href="https://bsky.app/profile/knowler.dev">Knowler</a> reviewed my draft PR, and all my PR anxieties came tumbling back. This was going to be The Perfect PR. How dare anyone look at it before I was ready to defend my work. What would they think about my abilities looking at my old copy and pasted portfolio site code that I hadn’t even finished translating from <a href="https://react.dev/">React</a> to <a href="https://vuejs.org/">Vue</a>? I was legitimately embarrassed someone was looking at my code in that state.</p>
<p>Fueled by embarrassment and productive procrastination, I sprung into action. In what little free time I had, I must have toggled my toggle a thousand times. Three days later, it was finally in a state I was happy with. It was time to open up my PR for review.</p>
<img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1771263500393/64bc78f5-dd9c-48b7-805b-fcba0456753a.png" alt=" Mona-Lisa Saperstein, played by Jenny Slate, hand outstretched, saying &quot;money please,&quot; but the meme is captioned &quot;review please&quot;" style="display: block;" width="806" height="454" loading="lazy">

<p>A couple dozen comments came in. Overwhelmed, I tried to remember that I had asked for this. I resolved most of the comments and left a comment saying I’d get to the last item, <a href="https://polypane.app/blog/forced-colors-explained-a-practical-guide/">forced colors mode</a>, in the morning. Frustrated with the code for the forced colors and myself for forgetting a few tiny things, I went to play games with friends.</p>
<p>A few hours later, I got a DM from Daniel. He had some code for my PR. I agreed with his reasoning for all the changes and found out an entire tooltip had been added while I was blissfully ignoring the rest of the repo. (I’m confident in my ability to merge or rebase my way out of any situation.)</p>
<p>Splitting my attention between <a href="https://store.steampowered.com/app/1203620/Enshrouded/">Enshrouded</a> and talking to Daniel, I felt defeated. I knew I finish the forced colors fix the next day, but also adding a tooltip felt daunting. Still, it felt like I needed to do it all.</p>
<h2 id="heading-collaboration-over-perfection">Collaboration Over Perfection</h2>
<p>And then I remembered, this wasn’t work and it wasn’t going to come up on a performance review. I wasn’t alone – Knowler and Daniel were taking the time to help me get this PR merged because they wanted to. I had the opportunity to collaborate with some brilliant people and see how they would write the same thing.</p>
<p>So I pushed through my perfectionism, demanded compliments, and asked Daniel to push his changes. I told him I’d review them in the morning.</p>
<p>Reviewing Daniel’s code, I found that he had forgotten a couple tiny things, just like I had. The code I was frustrated with the night before was legitimately frustrating. <a href="https://cssence.com/2024/forced-colors-mode-strategies/">Emulating forced colors on a Mac</a> was giving me weird and contradictory results. I needed to test on a Windows machine to finally get it right.</p>
<p>Then, six days after I opened the PR, I finally merged it. I was on top of the world. I had gotten my contribution in before our vacation (and more importantly, I had received multiple compliments). Finally, I knew what to write this blog about.</p>
<img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1771191470445/caeb7ab5-d54b-4dd9-907c-a95a85e650b1.png" alt="Abbey Perini Bluesky Elder I'd like to thank @knowler.dev and @danielroe.dev and my confidence in my git skills because this is the fastest moving repo I've ever been in. Quoted post - npmx @npmx.dev @abbeyperini.dev at chat.npmx.dev#contributing. A screenshot of the npmx Discord server. The npmx APP posted @Abbey Perini (abbeyperini) is now a contributor! Abbey Perini NERD responds with a gif of Jim Carrey as the Mask giving an acceptance speech and saying Thank You! with 6 raised hands reacts, 2 trophy reacts, and 2 clapping hands reacts 4:10 PM Feb 11, 2026" style="display: block;" width="1008" height="1254" loading="lazy">

<h2 id="heading-my-current-view-of-oss">My Current View of OSS</h2>
<p>When you’re looking for a project that interests you, the code isn’t the only thing to evaluate. Early in my career, I learned three rules for evaluating software tools.</p>
<ol>
<li>Check the date of the last update to make sure it’s actively maintained.</li>
<li>Look at the documentation. Is it up to date and easy to follow?</li>
<li>Check out the community. Do people get fairly quick responses to their questions?</li>
</ol>
<p>After joining npmx, I’ve discovered that, with a few tweaks, these rules also apply to evaluating an OSS project.</p>
<ol>
<li>Check out the last few tickets and PRs to see how fast the repo moves. If it’s fairly slow, you can probably claim an issue in GitHub easily. If it’s rapid, start by getting to know the community and how they’re assigning tickets.</li>
<li>You should always check the repo for a code of conduct, contributing guide, and sufficient documentation. Also evaluate the tickets. Are contributors expected to research solutions on their own or given strict requirements? How do maintainers respond to comments on issues?</li>
<li>Check out the community. An active, inclusive community makes contributing a lot more fun.</li>
</ol>
<p>Now, my view of OSS is much more nuanced. Yes, there are issues with OSS as whole, but there’s a reason people want to fix them. OSS can be collaborative, inspirational, and enjoyable.</p>
<h2 id="heading-tips-for-pr-authors-and-reviewers">Tips for PR Authors and Reviewers</h2>
<p>People underestimate the importance of the relationship between PR author and reviewer. A collaborative OSS code review process doesn’t happen in a vacuum. It takes careful cultivation by the PR author, PR reviewer, and project community.</p>
<p>For a long time, I focused on the responsibility of the reviewer to make the PR author comfortable (for example, compliments, gifs). Don’t get me wrong – I think one of the most important parts of a senior developer’s job is to provide constructive, actionable feedback.</p>
<p>But I now understand that the PR author’s sense of agency and desire to learn are just as important.</p>
<p>A sense of agency is a sense of control over actions and consequences. In other words, the PR author needs to feel that they have control over what goes into their PR. Before npmx, I understood this a little bit. I always ask “why?” because I’m not putting my name on code that I don’t understand and agree with. I have counseled my own junior developer that it’s his job to get PRs he’s authored reviewed and merged.</p>
<p>After experiencing an in-depth code review outside of work, I finally understand that a PR is a process. Reviews exist to get consensus, so “perfect” is far more subjective than I originally thought. There’s a reason you get a conversation, not a grade.</p>
<p>Maybe I’ll even ignore some nitpicks in the future.</p>
<p>A desire to learn makes remaining open to a reviewer’s suggestions and requests a lot easier. During my first npmx PR, it was only when my desire to learn outweighed my desire to prove something that I started having fun.</p>
<h2 id="heading-conclusion">Conclusion</h2>
<p>Today, March 3rd, 2026, is <a href="https://npmx.dev/blog/alpha-release">the alpha release of npmx</a>, and I am very proud to be a contributor and member of the community.</p>
<p>I look forward to learning about OSS from Patak, fancy, smart code from Daniel, outreach from Salma, and accessibility from Knowler. I know I’ll learn many things outside of that list, too. I’m grateful I’m not the smartest person in the room and that I finally get to have fun with Pull Requests.</p>
 ]]>
                </content:encoded>
            </item>
        
            <item>
                <title>
                    <![CDATA[ How to Save Multiple Drafts in Git: A Guide to Using Stash ]]>
                </title>
                <description>
                    <![CDATA[ Writing code can be similar to writing tutorials. In both cases, you’ll typically need to create and work on multiple drafts before reaching the final version. In an ideal setting, you would write cod ]]>
                </description>
                <link>https://www.freecodecamp.org/news/how-to-save-multiple-drafts-in-git-a-guide-to-using-stash/</link>
                <guid isPermaLink="false">6989f72cfec80c4e91c007a4</guid>
                
                    <category>
                        <![CDATA[ Git ]]>
                    </category>
                
                    <category>
                        <![CDATA[ GitHub ]]>
                    </category>
                
                    <category>
                        <![CDATA[ version control ]]>
                    </category>
                
                <dc:creator>
                    <![CDATA[ Chidiadi Anyanwu ]]>
                </dc:creator>
                <pubDate>Mon, 09 Feb 2026 15:03:08 +0000</pubDate>
                <media:content url="https://cdn.hashnode.com/res/hashnode/image/upload/v1770649372924/7c949e9d-627a-4b06-99fe-40ce0e7c8507.png" medium="image" />
                <content:encoded>
                    <![CDATA[ <p>Writing code can be similar to writing tutorials. In both cases, you’ll typically need to create and work on multiple drafts before reaching the final version.</p>
<p>In an ideal setting, you would write code for a feature, add that code to the staging area, and then commit it before going to the next part. This helps keep your commit history clean. (Don't worry if you don't have a clean history. Many of us don’t.)</p>
<p>But now, imagine a scenario where you have multiple features to build. You've committed the first. You've started the third, but then you found out you needed to build the second one first, because the third depends on it. It might seem like you have to go back in time and build out that second feature without mixing in the code changes for the third, and without deleting the code changes for the third.</p>
<p>So how do you do that?</p>
<p>In this article, you’re going to learn about Git stash, what it is, and the basic commands you need to be able to use it.</p>
<h2 id="heading-what-well-cover">What We’ll Cover:</h2>
<ul>
<li><p><a href="#heading-what-is-git-stash">What is Git Stash?</a></p>
</li>
<li><p><a href="#heading-how-to-use-git-stash">How to Use Git Stash</a></p>
<ul>
<li><p><a href="#heading-pushing-commands-to-the-stash">Pushing Commands To The Stash</a></p>
</li>
<li><p><a href="#heading-applying-changes-from-the-stash-to-the-working-directory">Applying Changes From The Stash To The Working Directory</a></p>
</li>
<li><p><a href="#heading-listing-the-items-in-the-stash-list">Listing The Items In The Stash List</a></p>
</li>
<li><p><a href="#heading-removing-items-from-the-stash">Removing Items From The Stash</a></p>
</li>
<li><p><a href="#heading-creating-a-new-branch-from-stash">Creating A New Branch From Stash</a></p>
</li>
<li><p><a href="#heading-showing-the-changes-in-the-stash">Showing The Changes In The Stash</a></p>
</li>
</ul>
</li>
<li><p><a href="#heading-conclusion">Conclusion</a></p>
</li>
</ul>
<p>To understand and get the most out of this tutorial, you’ll need to have a basic understanding of Git.</p>
<h2 id="heading-what-is-git-stash">What is Git Stash?</h2>
<p>Git stash provides storage (in the form of a stack) where you can store changes to your code. It lets you keep these changes separate from the current working directory until you're ready to apply them.</p>
<p><code>git stash</code> is a relatively simple command, and has a few variations like:</p>
<ul>
<li><p><code>git stash push</code></p>
</li>
<li><p><code>git stash pop</code></p>
</li>
<li><p><code>git stash apply</code></p>
</li>
<li><p><code>git stash drop</code></p>
</li>
<li><p><code>git stash clear</code></p>
</li>
<li><p><code>git stash show</code></p>
</li>
<li><p><code>git stash list</code></p>
</li>
</ul>
<h2 id="heading-how-to-use-git-stash">How to Use Git Stash</h2>
<h3 id="heading-pushing-code-changes-to-the-stash">Pushing Code Changes to the Stash</h3>
<p>To push uncommitted changes from the working directory to the stash, you can use <code>git stash push.</code> When you do that, the changes disappear from the working directory and are saved in the stash. The working directory is then set back to the last commit (which, in the example below, is the Feature one).</p>
<pre><code class="language-bash">git stash push
</code></pre>
<img src="https://cdn.hashnode.com/uploads/covers/5fc16e412cae9c5b190b6cdd/7652801b-cb1e-45cc-ac94-281512252f37.png" alt="7652801b-cb1e-45cc-ac94-281512252f37" style="display: block;" width="1019" height="382" loading="lazy">

<p>You can also write the <code>git stash push</code> command as just <code>git stash</code> – it means the same thing and performs the same way. You can also add a message to it with the <code>-m</code> or <code>--message</code> flag:</p>
<pre><code class="language-bash">git stash push -m "Feature two I was working on"
</code></pre>
<p>You can use the <code>-u</code> flag or <code>--include-untracked</code> to include untracked changes in the stash. This way, the changes not yet tracked by Git can be included in the stash.</p>
<pre><code class="language-bash">git stash push -u
git stash push --include-untracked
</code></pre>
<p>On the other hand, you can decide to push only staged changes to the stash with the <code>-s</code> or <code>--staged</code> flag:</p>
<pre><code class="language-bash">git stash push -s
</code></pre>
<p>You can also suppress feedback messages with the <code>-q</code> or <code>--quiet</code> flag:</p>
<pre><code class="language-bash">git stash push -q
</code></pre>
<p>When you're done with your edits on the current working directory, you can commit and push without the older changes bleeding into it. They're safely stowed away in the stash.</p>
<p>Anytime you use the git stash command, you add a stash to the stash list. The stashes are identified by their index numbers.</p>
<h3 id="heading-applying-changes-from-the-stash-to-the-working-directory">Applying Changes from the Stash to the Working Directory</h3>
<p>Let’s say you had a quick fix to do. You’re done committing that, and you want to continue with what you were working on. You can restore the changes from the stash to continue working on them.</p>
<p>You can do this by using the <code>git stash apply</code> command or the <code>git stash pop</code> command:</p>
<pre><code class="language-bash">git stash apply
</code></pre>
<img src="https://cdn.hashnode.com/uploads/covers/5fc16e412cae9c5b190b6cdd/89d30b86-ba75-412f-8aba-b8bf1ac32933.png" alt="89d30b86-ba75-412f-8aba-b8bf1ac32933" style="display: block;" width="1005" height="475" loading="lazy">

<p><code>git stash apply</code> applies the latest changes from the stash to the working directory, but doesn’t delete the code from the stash. You can select a particular entry to apply by index number:</p>
<pre><code class="language-bash">git stash apply --index stash@{1}
# You'd need to use quotes "stash@{1}" if you're writing this in PowerShell
</code></pre>
<img src="https://cdn.hashnode.com/uploads/covers/5fc16e412cae9c5b190b6cdd/4a26b84c-9bf0-4bd2-9687-7ebb94046f5d.png" alt="4a26b84c-9bf0-4bd2-9687-7ebb94046f5d" style="display: block;" width="1001" height="212" loading="lazy">

<p><code>git stash pop</code>, on the other hand, applies the latest changes from the stash, then deletes them from the stash. Basically, popping from a stack. You can select a particular stash entry to pop by index number.</p>
<pre><code class="language-bash">git stash pop
</code></pre>
<pre><code class="language-bash">git stash pop --index stash@{1}
# You'd need to use quotes "stash@{1}" if you're writing this in PowerShell
</code></pre>
<h3 id="heading-listing-the-items-in-the-stash-list">Listing the Items in the Stash List</h3>
<p>You can use <code>git stash list</code> to list out the stashes in the stash list. It’s arranged by index number (like {0}, {1}, and so on). Any time you do a git stash push, it adds a stash to the stash list.</p>
<pre><code class="language-bash">git stash list
stash@{0}: WIP on master: b2a2709 Feature one
stash@{1}: WIP on master: b2a2709 Feature one
</code></pre>
<img src="https://cdn.hashnode.com/uploads/covers/5fc16e412cae9c5b190b6cdd/46c7b4a8-6701-4227-8d48-9da354c9d1b7.png" alt="46c7b4a8-6701-4227-8d48-9da354c9d1b7" style="display: block;" width="1014" height="156" loading="lazy">

<h3 id="heading-removing-items-from-the-stash">Removing Items from the Stash</h3>
<p>You can use <code>git stash clear</code> to clear the stash list. But if you just want to drop a particular entry from the stash list, you can use <code>git stash drop</code> and specify the entry you want to drop by the index number. This doesn’t apply its changes to the working directory.</p>
<pre><code class="language-bash">git stash clear
</code></pre>
<pre><code class="language-bash">git stash drop stash@{0}
# You'd need to use quotes "stash@{0}" if you're writing this in PowerShell
</code></pre>
<h3 id="heading-creating-a-new-branch-from-stash">Creating a New Branch from Stash</h3>
<p>You can also create a new branch from a stash using <code>git stash branch</code>. The syntax is <code>git stash branch &lt;branchname&gt; [&lt;stash&gt;].</code></p>
<pre><code class="language-bash">git stash branch premium-branch stash@{0}
# You'd need to use quotes "stash@{0}" if you're writing this in PowerShell
</code></pre>
<img src="https://cdn.hashnode.com/uploads/covers/5fc16e412cae9c5b190b6cdd/a14db1c1-b0ac-4a81-ae4d-4b4859989489.png" alt="a14db1c1-b0ac-4a81-ae4d-4b4859989489" style="display: block;" width="1018" height="232" loading="lazy">

<p>If you don’t add the stash index, it will just use the last stash.</p>
<pre><code class="language-bash">git stash branch premium-branch
</code></pre>
<h3 id="heading-showing-the-changes-in-the-stash">Showing the Changes in the Stash</h3>
<p>You can use <code>git stash show</code> to show the changes you’ve made in your stashed changes.</p>
<pre><code class="language-bash">C:\file-path\git_stash_example&gt; git stash show
 text.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)
</code></pre>
<img src="https://cdn.hashnode.com/uploads/covers/5fc16e412cae9c5b190b6cdd/9d5a5e83-7c2f-4a2d-a004-f406b5ed1af7.png" alt="9d5a5e83-7c2f-4a2d-a004-f406b5ed1af7" style="display: block;" width="1008" height="196" loading="lazy">

<h2 id="heading-conclusion">Conclusion</h2>
<p>Git stash is one of those quiet tools that becomes indispensable once your workflow starts to get messy. It allows you to shelve unfinished ideas, switch context without panic, and keep your commits clean. With it, you can safely carry out urgent fixes, and juggle dependent features without muddling up your commit history.</p>
<p>If you enjoyed this article, share it with others. You can also reach me on <a href="https://linkedin.com/in/chidiadi-anyanwu">LinkedIn</a> or <a href="https://linkedin.com/in/chidiadi-anyanwu">X.</a></p>
 ]]>
                </content:encoded>
            </item>
        
            <item>
                <title>
                    <![CDATA[ Learn How to Use Git and GitHub – A Beginner-Friendly Handbook ]]>
                </title>
                <description>
                    <![CDATA[ In this handbook, you’re going to dive into something really exciting: Git and GitHub. To start, let’s clear one thing up: Git and GitHub are not the same thing. In short, Git is the tool that runs on your own computer and keeps track of changes in y... ]]>
                </description>
                <link>https://www.freecodecamp.org/news/learn-how-to-use-git-and-github-a-beginner-friendly-handbook/</link>
                <guid isPermaLink="false">693c859b176ed5964e28b921</guid>
                
                    <category>
                        <![CDATA[ GitHub ]]>
                    </category>
                
                    <category>
                        <![CDATA[ Git ]]>
                    </category>
                
                    <category>
                        <![CDATA[ Gitcommands ]]>
                    </category>
                
                <dc:creator>
                    <![CDATA[ Sumit Saha ]]>
                </dc:creator>
                <pubDate>Fri, 12 Dec 2025 21:14:03 +0000</pubDate>
                <media:content url="https://cdn.hashnode.com/res/hashnode/image/upload/v1765495440352/0eadf330-7a89-4328-aed1-3c851d279a5d.png" medium="image" />
                <content:encoded>
                    <![CDATA[ <p>In this handbook, you’re going to dive into something really exciting: Git and GitHub.</p>
<p>To start, let’s clear one thing up: Git and GitHub are not the same thing.</p>
<p>In short, Git is the tool that runs on your own computer and keeps track of changes in your files, while GitHub is an online platform that lets you store those Git projects in the cloud and collaborate with other people. Git works perfectly fine on its own, but GitHub makes teamwork, sharing, and backup much easier. They’re connected, yes, but completely different.</p>
<p>Think of it this way – Git is the “coffee,” and GitHub is the “coffee shop” where that coffee is served. Fun analogy, right? Don’t worry, in just a moment you’ll see exactly what that means.</p>
<h2 id="heading-what-does-git-do">What Does Git Do?</h2>
<p>So, let’s start by understanding what Git actually is and how it works. Simply put, Git is a powerful tool that constantly keeps track of every change you make to your files - and I mean <em>literally</em> all the time. Day or night, 365 days a year, Git records what changed, when it changed, who changed it, and even where it happened.</p>
<p>Now, what kind of files are we talking about? Almost any kind – not just code. It could be an image, a text file, JavaScript, PHP, Python, or even a video. No matter what you’re working on, Git tracks every single change. Pretty amazing, isn’t it?</p>
<p>But here’s the best part: the magic of Git doesn’t stop there. The coolest thing about Git is that it saves different versions of your files. Imagine you wrote some code and then made a few changes to it after a few days. Now you want to make sure the old version doesn’t get lost. That’s exactly where Git comes to the rescue. It lets you keep multiple versions of the same file effortlessly, and whenever you want, you can roll back to any previous version in just a moment.</p>
<p>By the end of this handbook, you’ll not only understand what Git and GitHub are, but you’ll also be able to use them confidently in real projects. You’ll learn how Git tracks changes locally, how repositories work, how to move changes through Git’s workflow, and how to collaborate with others using GitHub.</p>
<p>We’ll start from the very basics and gradually move toward more advanced concepts like branching, merging, resolving conflicts, and safely undoing mistakes – all with hands-on examples you can follow along with.</p>
<h2 id="heading-heres-what-well-cover">Here’s What We’ll Cover:</h2>
<ol>
<li><p><a class="post-section-overview" href="#heading-prerequisites">Prerequisites</a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-what-is-git">What is Git</a>?</p>
<ul>
<li><a class="post-section-overview" href="#heading-git-vs-github">Git vs GitHub</a></li>
</ul>
</li>
<li><p><a class="post-section-overview" href="#heading-git-architecture-local-and-remote">Git Architecture – Local and Remote</a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-how-to-install-git-on-your-computer">How to Install Git on Your Computer</a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-how-to-create-a-project-and-install-a-local-repository">How to Create a Project and Initialize a Local Repository</a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-how-to-create-a-remote-repository-on-github-and-clone-it">How to Create a Remote Repository on GitHub and Clone It</a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-how-to-track-changes-with-git-status">How to Track Changes with <code>git status</code></a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-how-to-move-changes-to-the-staging-agrea-with-git-add">How to Move Changes to the Staging Area with <code>git add</code></a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-how-to-save-work-permanently-with-git-commit-and-configure-git">How to Save Work Permanently with <code>git commit</code> (and Configure Git)</a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-how-to-delete-and-restore-files-with-git-rm-and-git-reset">How to Delete and Restore Files with <code>git rm</code> and <code>git reset</code></a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-how-to-view-commit-history-with-git-log">How to View Commit History with <code>git log</code></a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-branching-and-merging-in-git">Branching and Merging in Git</a></p>
<ul>
<li><a class="post-section-overview" href="#heading-understanding-merge-conflicts">Understanding Merge Conflicts</a></li>
</ul>
</li>
<li><p><a class="post-section-overview" href="#heading-how-to-navigate-history-with-git-checkout-and-compare-commits-with-git-diff">How to Navigate History with <code>git checkout</code> and Compare Commits with <code>git diff</code></a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-how-to-work-with-remotes-git-push-git-fetch-and-git-pull">How to Work with Remotes: <code>git push</code>, <code>git fetch</code>, and <code>git pull</code></a></p>
<ul>
<li><p><a class="post-section-overview" href="#heading-example-git-push">Example – <code>git push</code></a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-example-pushing-other-branches">Example – Pushing Other Branches</a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-example-git-fetch">Example – <code>git fetch</code></a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-example-git-pull">Example – <code>git pull</code></a></p>
</li>
</ul>
</li>
<li><p><a class="post-section-overview" href="#heading-how-to-undo-local-changes-with-git-restore">How to Undo Local Changes with <code>git restore</code></a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-how-to-temporarily-shelve-staged-work-with-git-stash">How to Temporarily Shelve Work with <code>git stash</code></a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-how-to-undo-commits-safely-with-git-revert">How to Undo Commits Safely with <code>git revert</code></a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-how-to-keep-history-clean-with-git-rebase">How to Keep History Clean with <code>git rebase</code></a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-how-to-collaborate-on-github-with-pull-requests">How to Collaborate on GitHub with Pull Requests</a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-git-amp-github-concise-summary">Git &amp; GitHub – Concise Summary</a></p>
<ul>
<li><p><a class="post-section-overview" href="#heading-git-vs-github">Git vs GitHub</a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-core-git-architecture-amp-workflow">Core Git Architecture &amp; Workflow</a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-getting-started">Getting Started</a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-seeing-amp-moving-changes">Seeing &amp; Moving Changes</a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-deleting-restoring-amp-undoing">Deleting, Restoring &amp; Undoing</a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-branching-merging-amp-conflicts">Branching, Merging &amp; Conflicts</a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-navigating-amp-comparing-history">Navigating &amp; Comparing History</a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-working-with-remotes-github">Working with Remotes (GitHub)</a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-temporarily-shelving-work-with-git-stash-1">Temporarily Shelving Work with git stash</a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-keeping-history-clean-with-git-rebase-1">Keeping History Clean with git rebase</a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-collaboration-with-pull-requests-prs">Collaboration with Pull Requests (PRs)</a></p>
</li>
<li><p><a class="post-section-overview" href="#heading-big-picture-takeaways">Big Picture Takeaways</a></p>
</li>
</ul>
</li>
<li><p><a class="post-section-overview" href="#heading-final-words">Final Words</a></p>
</li>
</ol>
<h2 id="heading-prerequisites">Prerequisites</h2>
<ul>
<li><p><strong>Basic File &amp; Folder Navigation</strong> – Using Finder / File Explorer.</p>
</li>
<li><p><strong>CLI Usage</strong> – Running simple commands in Terminal or Command Prompt.</p>
</li>
<li><p><strong>Text Editor</strong> – Any editor for opening and editing files.</p>
</li>
</ul>
<p>I’ve also created a video to go along with this article. If you’re the type who likes to learn from video as well as text, you can check it out below:</p>
<div class="embed-wrapper">
        <iframe width="560" height="315" src="https://www.youtube.com/embed/wNrbaAGE2PY" style="aspect-ratio: 16 / 9; width: 100%; height: auto;" title="YouTube video player" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen="" loading="lazy"></iframe></div>
<p> </p>
<h2 id="heading-what-is-git">What is Git?</h2>
<p>Git is most commonly used in coding projects, but its power goes far beyond just code. You can use Git to keep track of changes and maintain different versions of almost any file. This means you never have to worry about losing a file or accidentally overwriting something important.</p>
<p>Let’s look at a real-life example. Suppose you’re working on a project. You’ve spent hours writing code, your client loves it, and everything’s going great. Then, a month later, the client asks for some new changes. You make the updates as requested. But after a few days, the client comes back and says, “Actually, the old version was better.” Now you’re in trouble, right? Because you’ve already overwritten the original code. How do you get it back?</p>
<p>That’s exactly the kind of problem Git solves. This is why Git is known as a Version Control System – it keeps every version of your files or code safely stored, so you can go back to any previous state whenever you need to, without losing a thing.</p>
<p>Git was created by Linus Torvalds – the same brilliant mind behind Linux. And honestly, what he built is nothing short of genius. Most tools programmers use have a short lifespan, but Git is one of those rare ones that, once you learn it, stays useful for the rest of your career.</p>
<p>The best part? The basics of Git aren’t that hard to learn at all. It’s built around a few simple commands and concepts, and once you understand those, the whole system starts to make perfect sense.</p>
<p>Still, for beginners, Git can feel a little confusing at first – and that’s exactly why this handbook exists. Think of it not just as a tutorial, but as a complete learning resource for learning Git inside and out. We’ll cover all the essential topics you’ll actually use in real-world projects. And if you want to jump to a specific topic, you can easily find it by using the section headings in the table of contents after the intro.</p>
<p>If you follow this tutorial closely, you’ll be able to understand every part of Git, step by step.</p>
<h3 id="heading-git-vs-github">Git vs GitHub</h3>
<p>Now, let’s move on to another important topic: the difference between Git and GitHub. Git is a tool that runs locally on your own computer. It tracks all the changes you make to your files and keeps everything organized.</p>
<p>But imagine this: you and your teammate are working on the same project. You’re coding on your own computer, and your teammate is working from another one. That means you both have different versions of the same project, right? And if your team has more members, there will be even more versions – each saved separately on their own machines.</p>
<p>This is exactly where GitHub comes in. When the project is complete, you’ll need to combine everyone’s work into one place to merge all those changes together. For that, you need a central hub where everyone can upload their updates. You push your work there, your teammate pushes theirs, and GitHub brings it all together.</p>
<p>GitHub acts as that central online server where your team’s entire project lives, making it easy for everyone to see, edit, and share updates in one place, without any confusion.</p>
<p>But GitHub isn’t the only place where you can host your Git repositories. There are other popular platforms too, like GitLab and Bitbucket. These are also widely used and trusted by developers around the world. Still, among all of them, GitHub remains the most popular and widely adopted platform.</p>
<p>That’s why in this tutorial, our focus will mainly be on GitHub. It’s now owned by Microsoft and is maintained with great care and attention. Especially in the programming community and in the world of open-source projects, GitHub’s contribution is truly remarkable.</p>
<p>So without wasting any more time, let’s dive in and explore how Git and GitHub actually work – and see some real-world use cases that will help you understand their power in action.</p>
<h2 id="heading-git-architecture-local-and-remote">Git Architecture – Local and Remote</h2>
<p>Before you start working with Git, the most important thing is to understand its core concept: how it actually works and what its internal structure, or architecture, looks like.</p>
<p>Git is mainly divided into two major parts, <strong>Local</strong> and <strong>Remote</strong>.</p>
<ul>
<li><p>The <strong>Local</strong> part refers to your own computer, where you do all your work. This is where your files, code, and every change you make are stored.</p>
</li>
<li><p>The <strong>Remote</strong> part, on the other hand, lives in the cloud. It’s where you push or upload your local work. In most cases, when you say “remote,” you’re usually referring to GitHub.</p>
</li>
</ul>
<p>Now, let’s start with how the local part works. On your computer, the folder where you’re working on your project is called the <strong>Working Directory</strong>. This is where all the action happens: you write code, create new files, modify existing ones, and make changes as needed. And when you feel like, “Alright, this version looks good, I want to save this change,” that’s when you move on to the next stage in Git’s workflow.</p>
<p>So, what do you do next? You move your work to the “<strong>stage</strong>.” At first, this word might sound a bit unfamiliar, but once you use it a few times, it’ll make perfect sense. In simple terms, when you finish your work in the working directory, staging means you’re saying, “Alright, my changes are ready – they can move to the next step.” This staging process is the second phase in Git’s workflow.</p>
<p>Then comes the third phase where you take the staged files and send them to the local repository. You can think of the staging area as a middle ground – a temporary space where files sit between your working directory and the final save in the repository.</p>
<p>Once you’ve reviewed everything and you’re confident the work is correct, you “commit” it. Committing means permanently saving those changes to your local <strong>repository</strong> – that is, locking them in as a recorded version of your project’s history.</p>
<p>Now you might be wondering, what exactly is a repository? Simply put, a repository is a place where all the versions of your files and their complete change history are stored. In the case of a local repository, it’s a specific folder on your own computer. For a remote repository, it lives on a cloud server, like GitHub.</p>
<p>You can think of a repository as a digital cabinet for your code. It’s a secure place where Git neatly stores every record of your work and every change you’ve ever made. Inside this repository, Git automatically creates a few system files that track everything – your changes, history, commits, and more. These files are managed entirely by Git itself, and the whole system runs based on the data stored within them.</p>
<p>So if we summarize everything so far, it goes like this:</p>
<ol>
<li><p>You work inside your local working directory.</p>
</li>
<li><p>Once you’re done, you stage your changes.</p>
</li>
<li><p>Then you commit those staged files to the local repository.</p>
</li>
</ol>
<p>Up to this point, everything happens only on your own computer – nothing has been sent to the cloud yet. You need the cloud only when you want to share your code with others, access it from another computer, or keep it safely backed up.</p>
<p>That’s when you “push” your local repository to the remote repository. In other words, you upload it to GitHub. Think about it like this: just as you use Google Drive or OneDrive to store files, photos, or documents, you could technically keep everything only on your own device. But you store them in the cloud so that you can access them from anywhere, and even if something gets deleted locally, it stays safe online.</p>
<p>GitHub works the same way. It’s your cloud backup for code. So you see, the main purpose of this whole process is to make collaboration and remote access possible. Having a remote means you can easily send your code from the local repository to a cloud server, and if needed, pull that same code back to any other machine.</p>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765442130301/fa1908c2-c2ef-4a07-86dc-1d7d12b13a21.gif" alt="Git Architecture" width="1138" height="640" loading="lazy"></p>
<p>That’s the core idea of Git, and the foundation of the entire system rests on this simple concept. Beyond that, there’s nothing overly complex. Once you clearly understand this basic workflow, everything else in Git will feel much easier to grasp.</p>
<h2 id="heading-how-to-install-git-on-your-computer">How to Install Git on Your Computer</h2>
<p>Now, let’s see how to get started using Git from scratch.</p>
<p>The very first step before working with Git is installing it on your computer. It might already be installed on your machine, so just check first.</p>
<p>If you do need to install Git, you can download it directly from the <a target="_blank" href="https://git-scm.com/downloads">official website</a>. There, you’ll find different versions for the three major operating systems – Windows, macOS, and Linux. Simply choose the one that matches your system, and you’ll get clear download instructions right there.</p>
<p>If you’re on Windows, click on the Windows option, and you’ll see two download choices: one for 32-bit and another for 64-bit systems. Just pick the one that matches your setup, download it, and run the installer.</p>
<p>For Mac users, when you select the macOS option, you’ll also find instructions on how to install Git using <a target="_blank" href="https://brew.sh/">Homebrew</a>. Just follow those steps, and your installation will be done in no time.</p>
<p>And for those using Linux or other Unix-based systems, you can follow the installation guide provided on the site according to your distribution. The entire process is simple and straightforward.</p>
<p>Once you have Git installed, the next step is to open your terminal or command prompt. If you’re using a Mac, open the Terminal app. For Windows users, you can use either Command Prompt or PowerShell – both will work just fine.</p>
<p>But after installing Git, you’ll usually get a separate terminal called <strong>Git Bash</strong>. You can use that too if you prefer. Many developers like working in Git Bash because it feels very similar to a Linux terminal and makes running Git commands easy and intuitive.</p>
<p>On Windows, you can open Git Bash by right-clicking anywhere inside a folder and selecting <strong>“Git Bash Here”.</strong></p>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765568453563/43d574fe-ba17-4a8a-b7ae-ec0fa71d84eb.jpeg" alt="Open Git Bash from inside any folder" class="image--center mx-auto" width="916" height="638" loading="lazy"></p>
<p>You can also open it by searching for <strong>Git Bash</strong> from the Start menu.</p>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765568550303/8e54b211-475b-4774-bbf6-6b76674d8fcf.png" alt="Opening Git Bash from Start Menu" class="image--center mx-auto" width="1024" height="576" loading="lazy"></p>
<p>When it opens, you’ll see a terminal window that looks very similar to a Linux or macOS terminal, with a dark background and a command prompt ready to accept Git commands.</p>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765567732235/e6edfc98-778b-47be-a70e-97821fa243c1.png" alt="Git Bash Terminal" class="image--center mx-auto" width="2486" height="1510" loading="lazy"></p>
<p>For the rest of this tutorial, I’ll be using <strong>macOS with the default Terminal app</strong>, but the Git commands themselves are exactly the same on Windows (Git Bash) and Linux. If you’re using Windows or Linux, you can follow along using your terminal of choice – only the way you open the terminal may differ slightly.</p>
<p>So now open your terminal. The first thing you need to do is make sure Git is properly installed, right? To check that, type a simple command in the terminal:</p>
<pre><code class="lang-bash">git --version
</code></pre>
<p>Then press Enter. As soon as you do that, you’ll see an output on the terminal showing the version of Git installed on your machine. Keep in mind that the version number might not be the same for everyone – it depends on when you installed Git and which update you’re using.</p>
<p>If Git is installed correctly, you’ll see this version output. But if it isn’t installed, you’ll get an error message instead. Hopefully, Git is now properly set up on your machine, and you’re ready to start using it.</p>
<h2 id="heading-how-to-create-a-project-and-initialize-a-local-repository">How to Create a Project and Initialize a Local Repository</h2>
<p>Now it’s time to get hands-on and do some practical work. As I mentioned earlier, Git can be implemented in any file or folder, right? So first, you need to create a few files and folders to work with.</p>
<p>Start by navigating to the desktop using the terminal:</p>
<pre><code class="lang-bash"><span class="hljs-built_in">cd</span> ~/Desktop
</code></pre>
<p>Here, <code>cd</code> is a terminal command that stands for “change directory.” It simply means you’re moving from one folder to another. Hopefully, you’re already familiar with some basic terminal commands like <code>cd</code>, <code>pwd</code>, <code>touch</code>, and <code>mkdir</code>. If not, you can easily learn them using Google or tools like ChatGPT. They’re simple to understand.</p>
<p>Just remember, for Windows users, some of these commands might be slightly different. And keep in mind, commands like <code>cd</code>, <code>pwd</code>, <code>touch</code>, and <code>mkdir</code> are general terminal commands – not Git commands.</p>
<p>Now that you’re inside the Desktop directory, create a new folder where you’ll keep all your project files. Name it <code>git-one</code>:</p>
<pre><code class="lang-bash">mkdir git-one
</code></pre>
<p>Press Enter. You’ve now created a new folder named <code>git-one</code> inside the Desktop directory. Move into that folder like this:</p>
<pre><code class="lang-bash"><span class="hljs-built_in">cd</span> git-one
</code></pre>
<p>You’re now inside the <code>git-one</code> folder, and this is where your Git project begins. Inside the <code>git-one</code> folder, create two files:</p>
<pre><code class="lang-bash">touch one.txt
touch two.txt
</code></pre>
<p>Next, create another folder named <code>myfolder</code>:</p>
<pre><code class="lang-bash">mkdir myfolder
</code></pre>
<p>Then use <code>cd myfolder</code> to enter the folder. Inside this folder, create another file:</p>
<pre><code class="lang-bash">touch three.txt
</code></pre>
<p>Now check everything you’ve created in your file system. On macOS, for example, you can open the <code>git-one</code> folder in Finder by running:</p>
<pre><code class="lang-bash">open .
</code></pre>
<p>Here, the dot means “the current folder.” As soon as you press Enter, Finder opens up. Inside the <code>git-one</code> folder, you’ll see two files, <code>one.txt</code> and <code>two.txt</code>, and a folder named <code>myfolder</code>, which contains the <code>three.txt</code> file.</p>
<p>Now write something inside each of the files. Open <code>one.txt</code> in a text editor, write <code>one</code>, and save it. Then open <code>two.txt</code>, write <code>two</code>, and save that as well. Finally, go inside the <code>myfolder</code> directory, open <code>three.txt</code>, write <code>three</code>, and save it. Now all three files contain some content.</p>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765442159140/ff01dfea-fe75-4b27-9a91-8133cd538f1f.gif" alt="Finder Open Git One Folder" width="1138" height="640" loading="lazy"></p>
<p>This <code>git-one</code> folder is your <strong>working directory</strong>. As mentioned earlier, this is the folder where you’re doing all your work, and where all your files are stored.</p>
<p>If you want Git to start monitoring everything inside this <code>git-one</code> folder, you have to tell Git, “This is my project folder. Track all the changes here.” To do this, go back to the terminal, make sure you’re inside the <code>git-one</code> folder, and type this:</p>
<pre><code class="lang-bash">git init
</code></pre>
<p>The word <code>init</code> means “initialize.” In other words, you’re telling Git to start working inside this folder from now on. Once you run the command, it shows a message: “Initialized empty Git repository.” That means Git has now started tracking this folder.</p>
<p>So how do you know that? Since you’re inside the <code>git-one</code> folder, type this:</p>
<pre><code class="lang-bash">ls
</code></pre>
<p>You’ll see all the files and folders inside it. Now type:</p>
<pre><code class="lang-bash">ls -la
</code></pre>
<p>Notice that now you can also see a hidden directory named <code>.git</code>. The <code>ls -la</code> command lets you view hidden files and folders.</p>
<p>Operating systems hide certain files and folders by default to protect users from accidentally modifying or deleting critical system data. These hidden files usually store configuration, metadata, or internal information that regular users don’t need to touch. For example, you might see hidden files like <code>.env</code>, <code>.DS_Store</code>, or <code>.config</code> in different projects.</p>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765442184486/d3a47514-cf80-4401-ae98-cb96b8924464.png" alt="Git Init and Hidden .git Folder" width="2560" height="1440" loading="lazy"></p>
<p>You can see a hidden folder named <code>.git</code> inside your project directory. Who created it? Git did. This <code>.git</code> folder is actually the core of the entire project. It’s where Git keeps all its internal data, such as which files have changed, who made the changes, and what the previous versions were. In short, everything Git does is stored right here.</p>
<p>The <code>.git</code> folder is hidden for the same reason: it contains Git’s internal database and configuration. You normally never edit anything inside <code>.git</code> manually. If this folder is deleted or corrupted, Git loses the entire history of the project. Hiding it helps prevent accidental damage.</p>
<p>From now on, Git will be able to track every change you make in your work. Let’s say you make some changes to the three files you created earlier. That means you now have a <strong>local Git repository</strong>. By running <code>git init</code>, Git created the hidden <code>.git</code> folder and started tracking this directory as a repository. From this point on, any changes you make to files inside this folder can be staged, committed, and recorded in Git’s history. Even though you haven’t made a commit yet, the repository already exists locally and is ready to track your work.</p>
<h2 id="heading-how-to-create-a-remote-repository-on-github-and-clone-it">How to Create a Remote Repository on GitHub and Clone It</h2>
<p>You can also create a <strong>remote repository</strong> directly. I mentioned this earlier, so let’s see how to do it. Open your browser again and go to:</p>
<pre><code class="lang-text">https://github.com
</code></pre>
<p>If you’re new, you’ll need to create an account on GitHub first. If you’re already logged in, you’ll see your profile. On the left side, you can see your repositories, feeds, and other details. Your goal is to store your local files on GitHub.</p>
<p>To do that, you need to create a new repository on GitHub. Click the blue <strong>New</strong> button. Just like you used <code>git init</code> to create a local repository, here you can initialize one in the cloud. Give it a name – for example, <code>git-journey</code> – and in the description, write something like “You are learning Git and GitHub.” Keep it public so everyone can view it. Then click the <strong>Create Repository</strong> button. You’ve now created a new repository on GitHub.</p>
<p>Right now, the repository is completely empty – it doesn’t have any files in it. To add some files, click the <strong>Create a new file</strong> button, name it <code>one.txt</code>, and inside the file, write <code>one</code>. Then click the <strong>Commit changes</strong> button. The term “commit” basically means “save.” Committing is like saving a file – nothing complicated. Don’t worry about this too much now, as I’ll explain commits in more detail later.</p>
<p>For now, there’s already a default commit message saying “Create one.txt,” so you can keep that as it is and click <strong>Commit changes</strong>. Next, create another file the same way – this time naming it <code>two.txt</code>, writing <code>two</code> inside, and saving it. Now, if you check your GitHub repository, you can see two files there: <code>one.txt</code> and <code>two.txt</code>.</p>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765442212397/732bc0ff-60e4-4d43-a863-b1760453ec80.gif" alt="GitHub New Repository with Two Files" width="1138" height="640" loading="lazy"></p>
<p>At this point, you have two repositories – one on the cloud (GitHub), and another one locally on your computer. You initialized the local one yourself earlier, but now you want to bring the GitHub repository down to your machine by <strong>cloning</strong> it.</p>
<p>Go back to your terminal. Suppose you’re currently inside the <code>git-one</code> folder, but you want to clone the remote repository onto your Desktop. In the terminal, type:</p>
<pre><code class="lang-bash"><span class="hljs-built_in">cd</span> ../
</code></pre>
<p>This command takes you back to the Desktop. Now, you’re going to clone the remote repository – the one you just created on GitHub. For that, you need a link, which is the repository’s URL. Go back to GitHub, open that repository, and click on the <strong>Code</strong> button. There, you’ll see an HTTPS link. Copy that link. Then, in the terminal, type the following:</p>
<pre><code class="lang-bash">git <span class="hljs-built_in">clone</span> &lt;repository-https-link&gt;
</code></pre>
<p>Replace <code>&lt;repository-https-link&gt;</code> with the link you just copied, and press Enter. Git pulls your GitHub repository down onto your local machine.</p>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765442236567/d4ad9633-897c-421b-979f-121c77573078.gif" alt="Cloning GitHub Repository" width="1138" height="640" loading="lazy"></p>
<p>After a few moments, the cloning process is complete. To verify whether the repository has been successfully cloned, type in the terminal:</p>
<pre><code class="lang-bash">ls
</code></pre>
<p>Remember that this command shows the list of folders in your current location. You’ll see a new folder named <code>git-journey</code>, alongside your previous <code>git-one</code> folder. Enter the <code>git-journey</code> folder like this:</p>
<pre><code class="lang-bash"><span class="hljs-built_in">cd</span> git-journey
</code></pre>
<p>You’re now inside the <code>git-journey</code> directory. If you type this:</p>
<pre><code class="lang-bash">ls
</code></pre>
<p>you can see the contents of the folder. Inside it you should see the two files, <code>one.txt</code> and <code>two.txt</code>. To see hidden files, type:</p>
<pre><code class="lang-bash">ls -a
</code></pre>
<p>You’ll find a <code>.git</code> folder here as well. That proves this is also a complete Git repository, cloned from the cloud. Earlier, you saw the same thing in your local repository, right? So, this is how you can create a Git repository in two ways – one by initializing it locally, and the other by cloning it from GitHub or any other remote server. No matter which way you create it, to start working with Git, initialization is always required.</p>
<h2 id="heading-how-to-track-changes-with-git-status">How to Track Changes with <code>git status</code></h2>
<p>Now let’s look at something new. Suppose you’re currently inside the <code>git-journey</code> folder. This is the repository you just cloned from the remote, right? If you make any changes to this repository – for example, you open the file <code>one.txt</code> in a text editor, keep everything as it was, but add the number <code>1</code> at the end and save the file – you might want to know what exactly changed, or whether Git has detected the modification.</p>
<p>To check that, type in the terminal:</p>
<pre><code class="lang-bash">git status
</code></pre>
<p>As soon as you run this command, Git immediately tells you: <code>modified - one.txt</code>. This means Git has already detected the change you made in that file.</p>
<p>Now let’s say you make a small change in <code>two.txt</code> as well – just adding a <code>2</code> at the end – and then run <code>git status</code> again. This time it shows <code>modified - two.txt</code>. That means both files have been changed, and Git has detected both modifications.</p>
<p>This is exactly how Git continuously keeps an eye on every change you make. It’s like it’s always watching over your project. At any moment, you can run the <code>git status</code> command to see which files have been modified or updated.</p>
<p>In a real project, you’ll often work with multiple files at the same time, right? In that case, <code>git status</code> gives you a clear summary of the overall situation: what has changed, which files are new, and which ones are modified.</p>
<p>So, up to this point, you’ve learned that you can initialize Git in two ways – either locally or from a remote repository. And with <code>git status</code>, you can easily check what changes have been made in your working directory.</p>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765442263827/d48beb32-1dcf-4dc6-81df-a64adced52c1.gif" alt="Git Status Showing Modified Files" width="1138" height="640" loading="lazy"></p>
<p>Now let’s move out of the working directory into the staging area.</p>
<h2 id="heading-how-to-move-changes-to-the-staging-area-with-git-add">How to Move Changes to the Staging Area with <code>git add</code></h2>
<p>So far, you’ve only worked inside the <strong>working directory</strong>. That means you’ve created and modified files, but you haven’t yet told Git to keep those changes. Now you’re going to move them into the <strong>staging area</strong>.</p>
<p>In Git’s terminology, the process of moving changes from the working directory to the staging area is called <strong>adding</strong>. Simply put, <code>git add</code> means telling Git, “I want to keep this change.” Right now, inside the <code>git-journey</code> folder, you have two files, and both have been modified.</p>
<p>Now create another folder inside <code>git-journey</code>, named <code>myFolder</code>:</p>
<pre><code class="lang-bash">mkdir myFolder
</code></pre>
<p>Use <code>cd myFolder</code> to enter that folder. Inside <code>myFolder</code>, create a new file named <code>three.txt</code>:</p>
<pre><code class="lang-bash">touch three.txt
</code></pre>
<p>Open <code>three.txt</code> in your text editor, write <code>three</code>, and save the file. Now, you’ve made quite a few changes:</p>
<ul>
<li><p>You created a new folder.</p>
</li>
<li><p>You added a new file.</p>
</li>
<li><p>You modified some existing ones.</p>
</li>
</ul>
<p>Your entire project has gone through multiple changes. Go back to the repository’s root folder (the <code>git-journey</code> folder) by running this:</p>
<pre><code class="lang-bash"><span class="hljs-built_in">cd</span> ..
</code></pre>
<p>From here, check which files have actually been changed:</p>
<pre><code class="lang-bash">git status
</code></pre>
<p>Git shows that two text files have been modified, and a new folder has been created. Git also says that the old files are “tracked,” while the new folder is “untracked.” Why is that? Because the old files came from the remote repository you cloned earlier, so Git already knows about them. But since <code>myFolder</code> is newly created, Git doesn’t recognize it yet.</p>
<p>If you want to move everything to the staging area at once, you have two options: use <code>git add --all</code> or the shorter version <code>git add -A</code>. Both commands do exactly the same thing. Try it out:</p>
<pre><code class="lang-bash">git add --all
git status
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765442889338/448d6a6e-df96-4e74-be07-13d285f3ca5f.png" alt="Git Add All and Status" width="2560" height="1440" loading="lazy"></p>
<p>Git has staged everything. All the changes you made are now “ready to commit.” You’ll learn more about commits in detail later. For now, just remember that when you use <code>git add --all</code>, Git takes every change and prepares it for the next commit. If you want to go back to the previous state – that is, remove everything from the staging area and return them to the working directory – type this:</p>
<pre><code class="lang-bash">git reset
git status
</code></pre>
<p>You’ll notice everything is back to the earlier state.</p>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765442910152/1b8a64da-813c-4925-846f-0a0b5527aa76.gif" alt="Git Reset and Status" width="1138" height="640" loading="lazy"></p>
<p>Now try <code>git add -A</code>:</p>
<pre><code class="lang-bash">git add -A
git status
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765442932087/5eb27c66-5fee-4d87-bc11-2fee381e9288.png" alt="Git Add A and Status" width="2560" height="1440" loading="lazy"></p>
<p>You’ll see that Git has staged everything again. So whether you use <code>git add --all</code> or <code>git add -A</code>, both do the same thing – Git stages every change. Next, run:</p>
<pre><code class="lang-bash">git reset
git status
</code></pre>
<p>Everything is unstaged again. Now, in this state, if you type this:</p>
<pre><code class="lang-bash">git add .
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765442982841/bb3acfb7-b236-4230-8fd8-f48ef9c69093.png" alt="Git Add Dot and Status" width="2560" height="1440" loading="lazy"></p>
<p>at first glance it seems like it’s doing the same thing as <code>git add --all</code>, as everything appears to be staged. But there’s an important difference. Reset again:</p>
<pre><code class="lang-bash">git reset
</code></pre>
<p>Now go inside the <code>myFolder</code> directory:</p>
<pre><code class="lang-bash"><span class="hljs-built_in">cd</span> myFolder
git add .
git status
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443005193/c5d8a16e-d85d-431c-a56a-2a79326980fb.gif" alt="Git Add Dot Inside Folder and Status" width="1138" height="640" loading="lazy"></p>
<p>Git has only staged the <code>three.txt</code> file that’s inside <code>myFolder</code>. The other files in the root folder are still unstaged. This difference is really important:</p>
<ul>
<li><p><code>git add --all</code> or <code>git add -A</code> stage every change across the entire project.</p>
</li>
<li><p><code>git add .</code> stages only the changes within the <strong>current directory</strong> (and its subdirectories).</p>
</li>
</ul>
<p>Also, if there were a subfolder inside <code>myFolder</code>, using the dot would still include the files inside that subfolder too. In simple terms, the dot means “the current directory and everything inside it.”</p>
<p>So now you’ve seen three variations of the <code>git add</code> command: <code>--all</code>, <code>-A</code>, and <code>.</code> (dot). The first two work exactly the same way, while the dot version is limited to the current directory. Now run:</p>
<pre><code class="lang-bash">git reset
git status
</code></pre>
<p>to bring everything back again. Return to the root folder:</p>
<pre><code class="lang-bash"><span class="hljs-built_in">cd</span> ..
</code></pre>
<p>And stage everything again:</p>
<pre><code class="lang-bash">git add --all
</code></pre>
<p>Now all files are ready to commit. At this point, imagine you make some changes directly in the working directory. For example, you delete the file <code>two.txt</code> and create a new one named <code>four.txt</code>, writing <code>four</code> inside it. That means you’ve deleted one file and added another new one.</p>
<p>Check the status:</p>
<pre><code class="lang-bash">git status
</code></pre>
<p>Git shows that under “Changes to be committed,” the previously staged files are still there. But under “Changes not staged for commit,” it now lists <code>two.txt</code> as deleted and <code>four.txt</code> as untracked. Now type:</p>
<pre><code class="lang-bash">git add *
git status
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443030396/e69e74ab-9980-48f4-bf94-dd1fe525faea.png" alt="Git Add Asterisk and Status" width="2560" height="1440" loading="lazy"></p>
<p>Git has staged the newly created <code>four.txt</code> file, but it hasn’t staged the deleted <code>two.txt</code> file. That’s why it’s important to understand that <code>git add *</code> only stages <strong>new or modified files</strong>, but <strong>not deleted ones</strong>. So to summarize:</p>
<ul>
<li><p><code>git add *</code> stages visible new/modified files, but not deletions.</p>
</li>
<li><p><code>git add .</code> stages changes in the current directory, including modifications and deletions.</p>
</li>
<li><p><code>git add -A</code> / <code>git add --all</code> stage all changes (additions, modifications, deletions) across the entire repo.</p>
</li>
</ul>
<p>Reset again:</p>
<pre><code class="lang-bash">git reset
git status
</code></pre>
<p>If you want to stage only a specific file – say <code>one.txt</code>, which has been modified – you can do that by typing:</p>
<pre><code class="lang-bash">git add one.txt
</code></pre>
<p>Similarly, if you want to stage a file inside a folder (for example the file inside <code>myFolder</code>) you can write:</p>
<pre><code class="lang-bash">git add myFolder/three.txt
</code></pre>
<p>You can also stage a single file like this:</p>
<pre><code class="lang-bash">git add two.txt
git status
</code></pre>
<p>You’ll see that only <code>two.txt</code> has been staged. You can also stage files by their extension. For example, to stage all <code>.txt</code> files:</p>
<pre><code class="lang-bash">git reset
git add *.txt
git status
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443054715/07804ce7-1389-41bf-a48a-f2e83c3c3456.gif" alt="Git Add Txt Files and Status" width="1138" height="640" loading="lazy"></p>
<p>This command stages all <code>.txt</code> files in the current directory, excluding deleted ones and excluding files inside subfolders.</p>
<p>Finally, if you want to stage <strong>everything</strong> at once, a simple and common practice is to go to the root directory and type:</p>
<pre><code class="lang-bash">git add .
git status
</code></pre>
<p>All the changes are now staged together. That means all your changes have been moved from the working directory to the staging area.</p>
<h2 id="heading-how-to-save-work-permanently-with-git-commit-and-configure-git">How to Save Work Permanently with <code>git commit</code> (and Configure Git)</h2>
<p>So far, you’ve learned how to move changes from the working directory to the staging area using the <code>git add</code> command. Now let’s see how to save those changes from the staging area to the local repository. In Git’s language, this is called a <strong>commit</strong>. It means you’re confirming and saving your changes permanently.</p>
<p>You can think of it like getting ready for a party. You don’t just walk straight out the door. First, you stand in front of a mirror and check your clothes, shoes, accessories, and hair. That’s the stage where you make adjustments – maybe you realize, “This shirt doesn’t look good,” or “Let me change these shoes.” That’s an intermediate step. You haven’t left for the party yet – you’re just making sure everything is in order. If something’s off, you can fix it right there. Once you’re satisfied and everything looks perfect, that’s when you finally leave for the party.</p>
<p>Git works in the same way. Instead of going straight from the working directory to the local repository, you first move your changes to the staging area. This is an intermediate step where you can review, adjust, or even remove changes before saving them permanently. You don’t commit directly from the working directory because the staging area gives you a chance to verify everything before finalizing. When you finally “commit,” it means you’re sure everything is correct – no more mistakes – and now the work can be saved permanently. That’s why this process is called a commit.</p>
<p>First, check your current state:</p>
<pre><code class="lang-bash">git status
</code></pre>
<p>It shows that the staging area contains some changes that are ready but not yet committed. To commit them, write this:</p>
<pre><code class="lang-bash">git commit -m <span class="hljs-string">"I have made some changes to files"</span>
</code></pre>
<p>The <code>-m</code> flag lets you add a short message describing what you changed.</p>
<p>Sometimes an error may appear the first time you try to commit. When you install Git for the first time and attempt a commit, you might see a message like this:</p>
<pre><code class="lang-text">*** Please tell me who you are
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443087625/11b0ecda-49e6-48e6-9171-4b3ec11f4478.png" alt="Git Commit Error - Please Tell Me Who You Are" width="2560" height="1440" loading="lazy"></p>
<p>This is completely normal. It’s just Git’s way of asking for your identity before recording a commit. Git needs to know who is making the changes and from which email address. This information is attached to every commit in the project history, which later helps track who made which changes.</p>
<p>Fixing this issue is simple. Git tells you exactly what to do. Run the following two commands:</p>
<pre><code class="lang-bash">git config --global user.email <span class="hljs-string">"your@email.com"</span>
git config --global user.name <span class="hljs-string">"your name"</span>
</code></pre>
<p>By running these two commands, the problem is solved. The first command sets your email address, and the second sets your name. The <code>--global</code> flag means that this configuration will apply to your entire computer - so every Git commit you make from this machine will use the same name and email.</p>
<p>If you want to make the configuration specific to a single project, you can use the <code>--local</code> flag instead. That way, the settings will apply only to that particular repository.</p>
<p>In short, when you use Git for the first time, setting up your user configuration is mandatory. It’s part of the basic Git setup you need to do before committing. Once it’s configured, Git will automatically recognize your identity for all future commits. If Git is already configured, you don’t need to set it up again.</p>
<p>Now, let’s go back to the main task of making a commit:</p>
<pre><code class="lang-bash">git commit -m <span class="hljs-string">"I have made some changes to files"</span>
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443109452/9960deef-7e54-46f0-b0a2-328ab52a2b4a.png" alt="Git Commit Successful" width="2560" height="1440" loading="lazy"></p>
<p>Now the commit is done. The terminal shows how many files were changed, how many lines were added, and how many were deleted. You can verify everything by checking the status:</p>
<pre><code class="lang-bash">git status
</code></pre>
<p>Everything looks clean now, meaning all the changes have been successfully saved in the local repository. From now on, whenever you make new changes to any file, you’ll have to stage and commit them again, just like before.</p>
<p>One more thing about commits: you can always roll back to the previous state if needed. To do that, type the following:</p>
<pre><code class="lang-bash">git reset HEAD~
git status
</code></pre>
<p>This command will undo the last commit and bring everything back to the working directory. You’ll see that all the files have returned to the working directory, ready to be staged again. You can now modify or commit them as you wish.</p>
<p>This shows how much control Git gives you over your work. It’s just about remembering the right commands.</p>
<p>Before we move on to deleting and restoring files, go ahead and make a new commit again so you’re working from a clean state:</p>
<pre><code class="lang-bash">git add .
git commit -m <span class="hljs-string">"I have made some changes to files"</span>
</code></pre>
<h2 id="heading-how-to-delete-and-restore-files-with-git-rm-and-git-reset">How to Delete and Restore Files with <code>git rm</code> and <code>git reset</code></h2>
<p>Now the commit is done. Manually delete the <code>one.txt</code> file from your file system and then go back to the terminal. Type:</p>
<pre><code class="lang-bash">git status
</code></pre>
<p>Git shows that <code>one.txt</code> has been deleted. If you then type:</p>
<pre><code class="lang-bash">git add .
</code></pre>
<p>the deletion will also be staged. Instead of deleting a file manually and then adding it again, you can perform both steps in a single command. If you want to delete a file and stage that deletion at the same time, type:</p>
<pre><code class="lang-bash">git rm four.txt
</code></pre>
<p>Here, <code>four.txt</code> is just an example. This command deletes <code>four.txt</code> and automatically moves that change to the staging area. Once you run this and check the status:</p>
<pre><code class="lang-bash">git status
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443133023/f9d77e54-9829-4ff2-bd45-9e91b520bef0.gif" alt="Git Rm and Status" width="1138" height="640" loading="lazy"></p>
<p>you’ll notice that <code>four.txt</code> has been deleted and staged. You no longer have to perform two separate steps – deleting and adding manually. You can do both at once with this shortcut.</p>
<p>If you check in your file explorer, you’ll see that <code>four.txt</code> has disappeared. Now, roll back the deleted file using <code>git reset</code>. When you run a regular <code>git reset</code>, it only brings back the <strong>staged changes</strong>, not the deleted files. You’ll see the message “Unstaged changes after reset.” But if you check your file system, the deleted file hasn’t returned. That’s because a regular reset only brings back staging information, not the physical file. You can confirm this with:</p>
<pre><code class="lang-bash">git status
</code></pre>
<p>You’ll notice only the changes are back, and that manually deleted files are still missing. If you want to restore everything (both the changes and the deleted files) you have to run:</p>
<pre><code class="lang-bash">git reset --hard
</code></pre>
<p>Once you execute this, both your changes and the deleted files return to their previous state.</p>
<p>Now let’s explore the use of <code>git rm</code> a bit deeper. Suppose you want to remove a file. First, reset everything:</p>
<pre><code class="lang-bash">git reset --hard
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443156544/ba29878e-c5b8-48a8-8110-d7f80bc9d5be.gif" alt="Git Reset Hard" width="1138" height="640" loading="lazy"></p>
<p>Now you’re back to your original state. Edit the <code>four.txt</code> file and write <code>4</code> inside it. That means there’s now a modification in the working directory. If you try to delete it directly using:</p>
<pre><code class="lang-bash">git rm four.txt
</code></pre>
<p>the file isn’t deleted, and Git shows an error: “the following file has local modifications.” This means Git isn’t allowing the deletion because it has detected uncommitted changes in that file.</p>
<p>Before you can remove it, you either have to commit those changes or confirm that you truly want to discard them. If you’re sure you want to delete the file anyway, you can force it by using:</p>
<pre><code class="lang-bash">git rm -f four.txt
</code></pre>
<p>As soon as you run this command, the file is forcefully deleted. If you check your file explorer, you’ll see that <code>four.txt</code> is gone. Now consider another situation. Run another hard reset:</p>
<pre><code class="lang-bash">git reset --hard
</code></pre>
<p>This brings everything back again. Modify <code>four.txt</code> by writing <code>hello</code> inside it. Now, if you type:</p>
<pre><code class="lang-bash">git rm --cached four.txt
</code></pre>
<p>this removes the file from the staging area but keeps it physically in your working directory. Check it:</p>
<pre><code class="lang-bash">git status
</code></pre>
<p>You’ll see that <code>four.txt</code> has moved to the “Untracked files” section: it’s no longer staged, but the file itself still exists in the system. That’s the difference between the <code>--force</code> and <code>--cached</code> flags:</p>
<ul>
<li><p><code>git rm -f</code> completely deletes the file.</p>
</li>
<li><p><code>git rm --cached</code> removes the file from staging (and from tracking), but keeps it in your working directory.</p>
</li>
</ul>
<p>Another useful command is:</p>
<pre><code class="lang-bash">git rm -r folder
</code></pre>
<p>Here, the <code>-r</code> flag stands for “recursive.” This means if the folder contains other subfolders or files, all of them will be removed recursively. If you mention the folder name without <code>-r</code>, then only that folder will be removed, not its contents. Try this out. Reset everything again:</p>
<pre><code class="lang-bash">git reset --hard
</code></pre>
<p>Now experiment with <code>myFolder</code>:</p>
<pre><code class="lang-bash">git rm -r myFolder
git status
</code></pre>
<p>The folder is deleted from your file system as well, and <code>myFolder</code> is listed as deleted and staged automatically. Reset everything again:</p>
<pre><code class="lang-bash">git reset --hard
</code></pre>
<h2 id="heading-how-to-view-commit-history-with-git-log">How to View Commit History with <code>git log</code></h2>
<p>So far, you’ve made quite a few commits. Now you’ll learn how to view those commits. Viewing commits means checking the <strong>commit log</strong>. In the terminal, type:</p>
<pre><code class="lang-bash">git <span class="hljs-built_in">log</span>
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443180087/c4acc03d-e2a2-424e-b6e7-30b7cec94ddd.gif" alt="Git Log Showing Commit History" width="1138" height="640" loading="lazy"></p>
<p>You’ll see the full commit history. You might see three commits, for example. Along with each one, there are details and messages that clearly describe what was done in that commit.</p>
<p>You’ll also notice long random strings which are <strong>commit IDs</strong>. Using these IDs, you can go back to previous versions later on. The first two commits might be the ones created when you made files while setting up your GitHub repository, and the last one might be when you modified some files recently.</p>
<p>If you want to view this log in a cleaner, more compact format, you can use:</p>
<pre><code class="lang-bash">git <span class="hljs-built_in">log</span> --oneline
</code></pre>
<p>Once you run it, you’ll see a short summary of each commit with just the essential information. The commit IDs are also shown in a shortened format. These shortened IDs can also be used to return to any previous version later on.</p>
<h2 id="heading-branching-and-merging-in-git">Branching and Merging in Git</h2>
<p>Now let’s move on to one of Git’s most powerful and important features: <strong>branching</strong>. At the moment, your repository has only one branch. A branch in Git is like a separate line of development where you can work independently.</p>
<p>If you check the online repository you cloned earlier, you’ll see that the default branch is called <strong>main</strong>. This is the default branch where all work begins. In recent times, Git has shifted from calling it “master” to “main,” but the idea remains the same: the main branch is your project’s central line of development.</p>
<p>To understand branching more simply, imagine you’re working in the kitchen of a large restaurant. The <strong>main branch</strong> is the main kitchen where all the dishes are prepared and served to customers. Now, if your client wants to try a new dish or recipe, you wouldn’t experiment directly in that main kitchen, because if something goes wrong, it could ruin everything.</p>
<p>Instead, you create a separate <em>test kitchen</em> where you can safely prepare and test the new dish. Once the recipe is perfected, you bring it back into the main kitchen to serve it officially.</p>
<p>Git works exactly the same way. Instead of making changes directly in the main branch, you create a separate <strong>development branch</strong> where you test and commit all your changes. Once everything is stable and verified, you merge that branch back into the main branch. This ensures that your main project stays safe, while new features can be developed and tested without breaking anything.</p>
<p>In short, branching in Git provides a secure and organized intermediate step that allows you to review, test, and manage changes before merging them into the main codebase.</p>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443203531/fa09c9c1-c1e6-4617-bc35-8d16c7902b4d.gif" alt="Git Branching and Merging" width="1138" height="640" loading="lazy"></p>
<p>Since I’ve already mentioned the word “merge”, let’s understand what it means. <strong>Merging</strong> simply means combining the changes from two branches into one. It’s an important concept for understanding how branches work.</p>
<p>In Git, you can create multiple branches – like <code>staging</code>, <code>development</code>, <code>frontend</code>, or <code>backend</code> – and work on each of them separately. Once all the changes are finalized and tested, they’re merged back into the main branch.</p>
<p>Right now, your application has only one branch. To see how many branches you have, type:</p>
<pre><code class="lang-bash">git branch
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443230339/361868df-dc2f-4b01-8773-5a6b16fb721f.png" alt="Git Branch Command" width="2560" height="1440" loading="lazy"></p>
<p>This command shows the list of all branches. At the moment, you may have only one, and the branch you’re currently in has a star (<code>*</code>) next to it.</p>
<p>To create a new branch, type <code>git branch</code> followed by the branch name. For example:</p>
<pre><code class="lang-bash">git branch development
git branch
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443248217/e70e516a-1601-401e-a02a-6a25d020b97a.png" alt="Git Create New Branch" width="2560" height="1440" loading="lazy"></p>
<p>You’ll see two branches listed: <code>main</code> and <code>development</code>. The star next to <code>main</code> means you’re still on the main branch. You can easily switch from one branch to another.</p>
<p>When a new branch is created, it takes the exact state of the branch you were on at that moment. So, in this case, the <code>development</code> branch is an exact copy of the <code>main</code> branch. Whenever you create a new branch, it inherits the current state of the branch you’re in.</p>
<p>Now that you’ve created a new branch, switch to it:</p>
<pre><code class="lang-bash">git checkout development
git status
</code></pre>
<p>You’re now inside the <code>development</code> branch. If you check the status, everything looks clean, because the <code>development</code> branch was created with the same content as <code>main</code>. Go to your file system and create a new file named <code>three.txt</code>. Inside it, write <code>three</code>. Then, back in the terminal:</p>
<pre><code class="lang-bash">git status
git add .
git commit -m <span class="hljs-string">"I created three.txt and entered three there"</span>
</code></pre>
<p>Now your commit is done inside the <code>development</code> branch. Next, switch back to the main branch:</p>
<pre><code class="lang-bash">git checkout main
</code></pre>
<p>When you check your file system now, you’ll notice that <code>three.txt</code> is no longer there. Why? Because the changes made in the <code>development</code> branch exist only in that branch. Those changes haven’t been merged into <code>main</code> yet. The moment you switch back to <code>main</code>, Git automatically hides the changes made in <code>development</code>, showing you only what exists in the main branch.</p>
<p>This demonstrates how much control Git has over your file system. When you switch branches, Git instantly adjusts which files are visible so that you only see the changes relevant to that specific branch. There’s no duplication or conflict in your file system, as Git manages everything seamlessly.</p>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443271077/5e9a82df-941f-4692-8eb9-56da9e784085.gif" alt="Git Switch Branches and Isolated Changes" width="1138" height="640" loading="lazy"></p>
<p>In this way, you can create hundreds of branches, each containing its own set of changes, and Git will always show you a separate, isolated view for each one.</p>
<p>For any change to take effect, you must commit it. Whatever branch you’re working in, the commit must be made there. Once committed, Git understands that those changes belong exclusively to that specific branch. That’s why, when you switch back to the main branch, the changes made in the <code>development</code> branch don’t appear there.</p>
<p>Now suppose you make a new change to the <code>four.txt</code> file while you’re on the <code>main</code> branch – you add a <code>4</code> to it. Then, if you check the status:</p>
<pre><code class="lang-bash">git status
git add .
git commit -m <span class="hljs-string">"I changed four.txt and added additional 4"</span>
</code></pre>
<p>Now, both branches have changes – the <code>main</code> branch has this new commit, and the <code>development</code> branch still has its previous one. Since both branches now contain updates, you’ll need to merge the changes.</p>
<p>First, switch to the <code>development</code> branch:</p>
<pre><code class="lang-bash">git checkout development
</code></pre>
<p>Now run:</p>
<pre><code class="lang-bash">git merge main -m <span class="hljs-string">"merging main into development"</span>
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443302835/c0510bc0-f03f-4203-9d51-b2bac312af5a.png" alt="Git Merge Main into Development" width="2560" height="1440" loading="lazy"></p>
<p>After the merge, the changes made in the <code>main</code> branch appear inside the <code>development</code> branch as well. For example, the updated <code>four.txt</code> file is now present in the <code>development</code> branch alongside the previous changes. Both branches’ updates have been combined, and the <code>development</code> branch now reflects all the latest modifications.</p>
<p>Next, switch back to the <code>main</code> branch:</p>
<pre><code class="lang-bash">git checkout main
</code></pre>
<p>The changes from the <code>development</code> branch haven’t yet appeared here. From <code>main</code>, merge everything from <code>development</code>:</p>
<pre><code class="lang-bash">git merge development -m <span class="hljs-string">"merging on main with development"</span>
</code></pre>
<p>After running this command, you’ll see that the <code>three.txt</code> file from the <code>development</code> branch now appears in <code>main</code> as well. Both branches’ changes have been successfully merged, and the merge process is complete.</p>
<h3 id="heading-understanding-merge-conflicts">Understanding Merge Conflicts</h3>
<p>Sometimes during a merge, conflicts may occur. A <strong>merge conflict</strong> happens when the same part of a file has been changed differently in two branches.</p>
<p>For example, if you modified <code>one.txt</code> in the <code>main</code> branch and someone else modified the exact same section of <code>one.txt</code> in the <code>development</code> branch, Git won’t know which version to keep.</p>
<p>In such cases, Git flags the file as having a conflict, and you have to resolve it manually by deciding which changes to keep – or by merging both versions yourself.</p>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443321837/154fb298-dd45-496f-b1c9-cc68c6b228c2.gif" alt="Git Merge Conflict Example" width="1138" height="640" loading="lazy"></p>
<p>Right now, you’re on the <code>main</code> branch. From here, you’ll create a new branch so that <code>main</code> remains untouched while you simulate a conflict. Run:</p>
<pre><code class="lang-bash">git branch staging
git checkout staging
</code></pre>
<p>This creates a new branch named <code>staging</code>, which contains all the latest updates from <code>main</code>, and switches you to it. While working on the <code>staging</code> branch, go to <code>four.txt</code>. At the end of this file, there was the number <code>4</code>. Add <code>44</code> at the end and save the file. Now the <code>staging</code> branch has a change.</p>
<p>Run the following:</p>
<pre><code class="lang-bash">git status
git add .
git commit -m <span class="hljs-string">"changed 44"</span>
</code></pre>
<p>The <code>staging</code> branch work is done. Next, switch back to the <code>development</code> branch:</p>
<pre><code class="lang-bash">git checkout development
</code></pre>
<p>When you open <code>four.txt</code> here, you don’t see the <code>44</code> you added earlier in <code>staging</code>. So, write <code>444</code> and save the file. Then run:</p>
<pre><code class="lang-bash">git add .
git commit -m <span class="hljs-string">"added 444 on four.txt"</span>
</code></pre>
<p>The <code>development</code> branch now has its own separate change. While staying in the <code>development</code> branch, try to merge the changes from the <code>staging</code> branch:</p>
<pre><code class="lang-bash">git merge staging
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443344910/2991cf21-6397-45cb-aa96-70467a1244f8.png" alt="Git Merge Conflict Error" width="2560" height="1440" loading="lazy"></p>
<p>Git fails to merge automatically and shows an error:</p>
<pre><code class="lang-text">Automatic merge failed; fix conflicts and then commit the result.
</code></pre>
<p>This happens because the same line in <code>four.txt</code> was modified in both branches, <code>staging</code> and <code>development</code>. Git can’t decide which version should take priority, so it leaves the decision to you.</p>
<p>In this case, the developer working on the <code>development</code> branch (or whoever is managing it) has to manually resolve the conflict. When you open <code>four.txt</code> in a text editor, Git marks the conflicting section clearly, showing which part came from <code>staging</code> and which part came from <code>development</code>. You’ll see both the <code>44</code> from <code>staging</code> and the <code>444</code> from <code>development</code>. It’s now up to you to decide whether to keep one, remove one, or combine both changes.</p>
<p>While staying on the <code>development</code> branch, you decide which version to keep – for example, <code>444</code>. You’ll then need to remove all the conflict markers, save the file, and then run:</p>
<pre><code class="lang-bash">git add .
git commit -m <span class="hljs-string">"merge conflict solved"</span>
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443365329/94fbc5e8-2cca-4423-b4ab-4f90898ea9c0.gif" alt="Git Merge Conflict Markers" width="1138" height="640" loading="lazy"></p>
<p>Now switch back to the <code>staging</code> branch:</p>
<pre><code class="lang-bash">git checkout staging
</code></pre>
<p>When you open the file system and check <code>four.txt</code>, it still shows <code>44</code>, meaning no change has been applied yet. At this point, you can choose to merge changes either into <code>staging</code> or <code>development</code> since both branches are now in sync in terms of expected final content.</p>
<p>From <code>staging</code>, run:</p>
<pre><code class="lang-bash">git merge development
</code></pre>
<p>This time, Git merges everything smoothly without any conflict because both sides now contain compatible content. When you check the status:</p>
<pre><code class="lang-bash">git status
</code></pre>
<p>it shows everything is clean. Now, if you want to bring these merged changes into the <code>main</code> branch, switch to it:</p>
<pre><code class="lang-bash">git checkout main
</code></pre>
<p>Once you’re on the <code>main</code> branch and open the file system, you may notice that <code>four.txt</code> doesn’t yet have the latest update. Merge the <code>staging</code> branch:</p>
<pre><code class="lang-bash">git merge staging
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443386891/5b346d56-073a-4e58-a34c-736e2a25ba23.gif" alt="Git Merge Staging into Main" width="1138" height="640" loading="lazy"></p>
<p>All the latest changes flow into the <code>main</code> branch. The updates from both branches now combine into the final version. That’s how the entire process of merging and resolving merge conflicts works. You’ve now seen how branching works and how to switch from one branch to another using <code>git checkout</code>. Let’s dig a bit deeper into that command.</p>
<h2 id="heading-how-to-navigate-history-with-git-checkout-and-compare-commits-with-git-diff">How to Navigate History with <code>git checkout</code> and Compare Commits with <code>git diff</code></h2>
<p>Earlier, when we talked about <code>git log</code>, I mentioned that you can go back to a previous version using a commit ID. That’s what you’ll see now – and to do that, you’ll again use <code>git checkout</code>.</p>
<p>First, check your commit history:</p>
<pre><code class="lang-bash">git <span class="hljs-built_in">log</span> --oneline
</code></pre>
<p>Suppose you have nine commits in your log. Make a small change. Open <code>one.txt</code> and write <code>hello</code> inside it. Then stage and commit:</p>
<pre><code class="lang-bash">git add .
git commit -m <span class="hljs-string">"update one.txt file"</span>
</code></pre>
<p>Next, run:</p>
<pre><code class="lang-bash">git <span class="hljs-built_in">log</span> --oneline
</code></pre>
<p>All the commits are displayed. Now let’s say you want to switch back to one of your previous commits, specifically the one named “merging main into development.” To do that, copy the commit ID of that commit and type:</p>
<pre><code class="lang-bash">git checkout &lt;that-commit-id&gt;
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443408851/61803cda-c1d2-4b19-a298-bf569e3e36f8.gif" alt="Git Checkout Previous Commit" width="1138" height="640" loading="lazy"></p>
<p>Earlier, when you switched branches, you used the branch name. This time, you’re using a commit ID instead. Remember, your commit ID will be different.</p>
<p>After running this command, the project moves from the <code>main</code> branch to the exact state it was in at that previous commit. You must ensure that all your changes on <code>main</code> are tracked and committed before doing this. If there are any untracked or uncommitted files, Git won’t allow you to checkout to a previous version.</p>
<p>Once you run the command, you’ll see that in the terminal, instead of showing <code>main</code>, it now says something like:</p>
<pre><code class="lang-text">HEAD detached at &lt;commit-id&gt;
</code></pre>
<p>That means you’ve successfully switched to that particular commit. If you open <code>one.txt</code> now, you’ll notice that the <code>hello</code> line you added earlier is no longer there. This confirms that you’ve returned to the previous version of your project.</p>
<p>If you want to go back to your latest state – meaning returning to the main branch – use:</p>
<pre><code class="lang-bash">git checkout main
</code></pre>
<p>You’ve switched back to the <code>main</code> branch, and you’re back to the most recent version of your project.</p>
<p>So now you’ve seen how to switch between commits and move from one version to another. Now we’ll explore how to compare one commit with another.</p>
<p>If you want to see the differences between your current commit and a previous commit (that is, what lines of code were added, what lines were deleted), you can do that easily using Git commands.</p>
<p>First, check your commit history again:</p>
<pre><code class="lang-bash">git <span class="hljs-built_in">log</span> --oneline
</code></pre>
<p>Suppose there are now 10 commits in total. You’ll compare the commit “update one.txt file” with the previous one “merging main into development.” For that, you’ll need the commit IDs of both.</p>
<p>Since you’ve already run <code>git log</code>, copy those two IDs. Once you have them, write the command:</p>
<pre><code class="lang-bash">git diff &lt;first-commit-id&gt; &lt;second-commit-id&gt;
</code></pre>
<p>After running this command, Git shows the exact changes made between those two commits. The terminal displays which files were changed, what was removed (usually in red), and what was added (usually in green).</p>
<p>One important detail: in <code>git diff</code>, when you place the most recent commit ID first and the older one second, Git shows differences from the perspective of the newer commit – that is, what’s newly added or removed compared to the older one. If you reverse the order (older commit ID first and newer second), Git shows the opposite perspective. Try running the command both ways a few times and you’ll easily understand how the comparison works.</p>
<p>If you’re ever inside an interactive log or diff view, you can exit by pressing <code>q</code> on your keyboard. That closes the view immediately.</p>
<h2 id="heading-how-to-work-with-remotes-git-push-git-fetch-and-git-pull">How to Work with Remotes: <code>git push</code>, <code>git fetch</code>, and <code>git pull</code></h2>
<p>So far, everything you’ve done has been inside your local repository – staging files, making commits, and storing everything locally. But the real goal is to send those updates to the remote repository, like GitHub.</p>
<p>When you send local changes to a remote repository, that process is called a <strong>push</strong>. If any changes have been made in the remote repository that you want to bring into your local repository, you can use <strong>fetch</strong>.</p>
<p>When you run <code>git fetch</code>, the remote changes are downloaded into your local repository’s memory, but they won’t appear in your working directory yet. To update your working directory and see those changes in your files, you need to run <strong>git pull</strong>.</p>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443429569/e3d2882f-ad8e-4766-aa02-45633a983932.gif" alt="Git Push Fetch Pull" width="1138" height="640" loading="lazy"></p>
<p>In short:</p>
<ul>
<li><p><strong>push</strong> sends local changes to the remote.</p>
</li>
<li><p><strong>fetch</strong> brings remote changes into your local repository (but does not merge them into your working directory).</p>
</li>
<li><p><strong>pull</strong> fetches and merges; it updates your working directory immediately.</p>
</li>
</ul>
<p>In other words:</p>
<pre><code class="lang-text">git pull = git fetch + git merge
</code></pre>
<h3 id="heading-example-git-push">Example: <code>git push</code></h3>
<p>You’ve already made several changes in your local repository, and now you want to push them to the remote <code>main</code> branch. Since you’re currently on the <code>main</code> branch, use:</p>
<pre><code class="lang-bash">git push origin main
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443452657/0e0d3603-bc38-4ec0-9517-687dbf83c393.gif" alt="Git Push Main Branch" width="1138" height="640" loading="lazy"></p>
<p>Here, <code>origin</code> refers to the remote repository, and <code>main</code> is the branch you want to push to. After running this command, all your latest commits are sent to the remote <code>main</code> branch. If you check your repository on GitHub, you’ll see that everything is updated. But only the <code>main</code> branch is pushed – other branches aren’t uploaded yet. This means you’ve only pushed your <code>main</code> branch to the remote’s <code>main</code>.</p>
<h3 id="heading-example-pushing-other-branches">Example: Pushing Other Branches</h3>
<p>Switch to the <code>staging</code> branch:</p>
<pre><code class="lang-bash">git checkout staging
git push origin staging
</code></pre>
<p>Git creates a new branch named <code>staging</code> in the remote repository and pushes all your staging changes there. When you check GitHub again, you’ll see that the <code>staging</code> branch has been created and updated.</p>
<p>Similarly, switch to the <code>development</code> branch:</p>
<pre><code class="lang-bash">git checkout development
git push origin development
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443476135/9243730d-5d93-48aa-9d32-27ced9d8a762.gif" alt="Git Push Other Branches" width="1138" height="640" loading="lazy"></p>
<p>The <code>development</code> branch is also uploaded to the remote. Now all three branches (<code>main</code>, <code>staging</code>, and <code>development</code>) are fully synced with the remote repository.</p>
<p>Finally, switch back to the <code>main</code> branch again:</p>
<pre><code class="lang-bash">git checkout main
</code></pre>
<h3 id="heading-example-git-fetch">Example: <code>git fetch</code></h3>
<p>Imagine you’ve already pushed your local changes to the remote. Now let’s see how <code>git fetch</code> works.</p>
<p>Suppose you make a change directly on GitHub. For example, open the file <code>three.txt</code> on GitHub, type <code>3</code>, and commit the change. Now, the remote <code>main</code> branch has a new update that your local <code>main</code> branch doesn’t have – it’s behind the remote version. While staying on the local <code>main</code> branch, bring in the latest changes from the remote:</p>
<pre><code class="lang-bash">git fetch
</code></pre>
<p>Git fetches the new changes from the remote repository, but those updates don’t yet appear in your local file system. For example, you won’t see the update in <code>three.txt</code> until you merge the fetched changes. Once you run:</p>
<pre><code class="lang-bash">git merge
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443499165/ff4f6389-ad36-434e-a2b2-8c321160607a.gif" alt="Git Fetch and Merge" width="1138" height="640" loading="lazy"></p>
<p>the remote changes are integrated into your local working directory as well.</p>
<h3 id="heading-example-git-pull">Example: <code>git pull</code></h3>
<p>Now, suppose you edit the remote <code>three.txt</code> file again, this time adding <code>33</code> after <code>3</code> and committing it on GitHub. The remote <code>main</code> branch is now ahead again.</p>
<p>To bring in all those updates and merge them into your local <code>main</code> branch at once, use:</p>
<pre><code class="lang-bash">git pull
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443520831/0c438637-75f5-4743-a2d7-38cea3cd0d2e.gif" alt="Git Pull Command" width="1138" height="640" loading="lazy"></p>
<p><code>git pull</code> automatically performs both fetch and merge in a single command, meaning all the new remote changes, including the latest updates in <code>three.txt</code>, immediately appear in your local files.</p>
<p>You’ve now learned how to:</p>
<ul>
<li><p>push changes from local to remote (<code>git push</code>),</p>
</li>
<li><p>fetch changes from remote without merging (<code>git fetch</code>), and</p>
</li>
<li><p>pull changes from remote while merging them automatically (<code>git pull</code>).</p>
</li>
</ul>
<p>These three commands are among the most frequently used Git operations and are more than enough for most daily development work.</p>
<h2 id="heading-how-to-undo-local-changes-with-git-restore">How to Undo Local Changes with <code>git restore</code></h2>
<p>Now imagine you’re working on a project. You start developing a new feature, write a lot of new code, and modify several existing files. After some point, you realize that the approach you took isn’t working at all. But by then, you’ve already made changes across 10 to 15 different files – some with new code, some heavily modified.</p>
<p>In this situation, you want to discard everything and go back to the previous state. Would you really open each of those 10 to 15 files manually, remove all the new lines, and try to restore the old code one by one? How accurate or even possible would that be? Probably not at all.</p>
<p>In this case, the simplest answer is that it’s actually not practical manually. And the more complicated answer is that there’s no guarantee that everything will return to its exact previous state. This is exactly where the magic of the <code>git restore</code> command comes in.</p>
<p>The <code>git restore</code> command helps you revert any file or directory back to its previous state, meaning the state of the <strong>last commit</strong>. It’s mainly used to undo local uncommitted changes, or to remove changes that were added to the staging area using <code>git add</code>. Let’s test it. Suppose in <code>one.txt</code>, you write:</p>
<pre><code class="lang-text">new feature
</code></pre>
<p>This repository already had some committed history. Now you’re just trying to develop a new feature. After writing the new code, you realize that the change you made in <code>one.txt</code> (adding <code>new feature</code>) was a mistake. The previous version was fine.</p>
<p>Since this change isn’t ready to be committed, you want to undo it and go back to the last committed state. To do that, run:</p>
<pre><code class="lang-bash">git restore one.txt
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443545767/6e1bb71b-4228-40f5-bcec-23d094254355.gif" alt="Git Restore Single File" width="1138" height="640" loading="lazy"></p>
<p>As soon as you run this command, the file instantly reverts to its previous state – the exact version from the most recent commit.</p>
<p>If you want to restore an entire directory instead of a single file, type the directory name after <code>git restore</code> and it’ll bring everything in that folder back to the last committed version.</p>
<p>If you want to undo all changes across the entire repository, run:</p>
<pre><code class="lang-bash">git restore .
</code></pre>
<p>This restores every file to its last committed state. If you’ve already staged some changes using <code>git add</code>, you can still undo them using the <code>--staged</code> flag. For example:</p>
<pre><code class="lang-bash">git restore --staged fileName
<span class="hljs-comment"># or</span>
git restore --staged .
</code></pre>
<p>This removes the files from the staging area but keeps the working directory unchanged.</p>
<p>In summary, the <code>git restore</code> command helps you bring any file or directory back to its previous (last committed) state. It’s mainly used to undo local, uncommitted changes before they’re ever committed.</p>
<h2 id="heading-how-to-temporarily-shelve-work-with-git-stash">How to Temporarily Shelve Work with <code>git stash</code></h2>
<p>Now imagine this: you’re working on a new branch, developing a big feature. It’s a long process, and you’ve already finished about half of it. But the work isn’t yet in a state to be committed.</p>
<p>Suddenly, another developer messages you saying there’s a new update on a different branch and you need to check it and give feedback. How will you switch branches without losing your unfinished work? Will you throw away all your progress using the <code>git restore</code> command?</p>
<p>Of course not. There’s no reason to go through that kind of hassle when Git gives you a much smarter way to handle this: using the <code>git stash</code> command.</p>
<p>With <code>git stash</code>, you can temporarily set aside your unfinished work, switch to another branch to do something else, and later bring all your changes back with a single command.</p>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443582135/733a4f46-6c92-4902-8c45-97cdcd55990f.gif" alt="Git Stash Command" width="1138" height="640" loading="lazy"></p>
<p>Let’s see how it works. Suppose in <code>one.txt</code>, you write:</p>
<pre><code class="lang-text">another feature
</code></pre>
<p>You’re currently on the <code>main</code> branch. Now you need to switch to the <code>development</code> branch to review a new feature. So you type:</p>
<pre><code class="lang-bash">git checkout development
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443604514/8d70a915-8cac-49c8-8776-f4db7ed37bb5.png" alt="Git Checkout Development Branch with Uncommitted Changes" width="2560" height="1440" loading="lazy"></p>
<p>But Git throws an error:</p>
<pre><code class="lang-text">error: Your local changes to the following files would be overwritten by checkout:
    one.txt
Please commit your changes or stash them before you switch branches.
Aborting
</code></pre>
<p>This happens because Git doesn’t allow switching branches when there are uncommitted changes – it’s protecting your work. But since your feature isn’t ready to be committed, this is exactly when you use <code>git stash</code>. Run:</p>
<pre><code class="lang-bash">git stash
</code></pre>
<p>The moment you execute this command, your uncommitted changes disappear from your working directory – but they’re not lost. Git has safely stored them in a temporary area called the <strong>stash</strong>. This lets you switch branches freely without affecting your unfinished work. Now, switch to the <code>development</code> branch:</p>
<pre><code class="lang-bash">git checkout development
</code></pre>
<p>You’ve now successfully switched branches. You can review the new feature, make notes, and do whatever you need to. Once you’re done, switch back to your <code>main</code> branch again:</p>
<pre><code class="lang-bash">git checkout main
</code></pre>
<p>Now, when you look around, you’ll see that your unfinished feature – the one you were working on earlier – isn’t there. It’s still saved in the stash. To bring it back, “pop” it out of the stash:</p>
<pre><code class="lang-bash">git stash pop
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443623961/17568e8b-ba41-4020-b7f2-00a9ae690a9c.gif" alt="Git Stash Use Example" width="1138" height="640" loading="lazy"></p>
<p>As soon as you run this, all your stashed changes reappear in your working directory. The <code>pop</code> command restores the most recently stashed work and simultaneously removes it from the stash list. If you’ve stashed multiple times, Git keeps them all in order – newest on top, oldest at the bottom. When you pop, it brings back the most recent one first.</p>
<p>If you want to reapply the stashed changes <strong>without removing them</strong> from the stash list (so that you can reuse them later), use the <code>apply</code> command instead:</p>
<pre><code class="lang-bash">git stash apply
</code></pre>
<p>Your changes are restored, but they also remain safely stored in the stash for future use. You can stash again:</p>
<pre><code class="lang-bash">git stash
git stash apply
</code></pre>
<p>You’ll notice it behaves almost the same as before, and the changes come back just like when you used <code>pop</code>. You already know that Git can store multiple stashes, and you can view a list of all those stashed changes. To see that list, type:</p>
<pre><code class="lang-bash">git stash list
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443645465/12d2c1f3-a529-4d36-aa55-2ff459a20b2c.gif" alt="Git Stash List Command" width="1138" height="640" loading="lazy"></p>
<p>You’ll see a list of all your saved stashes. Each stash item is marked with an identifier like <code>stash@{0}</code>, <code>stash@{1}</code>, and so on. You can use these identifiers to apply or pop specific stashes:</p>
<pre><code class="lang-bash">git stash pop stash@{0}
<span class="hljs-comment"># or</span>
git stash apply stash@{0}
</code></pre>
<p>Both commands work. The only difference is how they handle the stash afterward. To understand the difference more clearly, suppose you check your stash list:</p>
<pre><code class="lang-bash">git stash list
</code></pre>
<p>and see just one stash. If you previously used <code>git stash apply</code>, that stash item is still there. To remove a stash manually, use <code>git stash drop</code>. The <code>drop</code> command removes a specific stash from the stash list. For example:</p>
<pre><code class="lang-bash">git stash drop
git stash list
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443664000/db9707b8-d32b-451c-8bd8-a0c992ef4f78.gif" alt="Git Stash Drop Command" width="1138" height="640" loading="lazy"></p>
<p>Now the stash list is empty. Since you used <code>git stash apply</code> earlier, all the changes are still in your working directory. Confirm that with:</p>
<pre><code class="lang-bash">git status
</code></pre>
<p>The changes you applied are still there. Now stash those changes again:</p>
<pre><code class="lang-bash">git stash
git stash list
</code></pre>
<p>You’ll see one stash entry again.</p>
<p>Then run:</p>
<pre><code class="lang-bash">git stash pop
git stash list
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443683035/cdd67489-7797-4cce-a0de-a10506244460.gif" alt="Git Stash Pop Command" width="1138" height="640" loading="lazy"></p>
<p>The stashed changes are restored into your working directory, and the stash list is now empty. <code>pop</code> brings your changes back <strong>and removes</strong> them from the stash list – it’s like taking them out permanently. Stash something again:</p>
<pre><code class="lang-bash">git stash
git stash list
</code></pre>
<p>Now run:</p>
<pre><code class="lang-bash">git stash apply
git stash list
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443701166/3df82aab-14d7-461a-8ee6-320609d3fdcb.gif" alt="Git Stash Apply Command" width="1138" height="640" loading="lazy"></p>
<p>The command works. Your files are restored, just like before. But the stash is still in the list. So here’s the key difference:</p>
<ul>
<li><p><code>git stash pop</code> restores your changes <strong>and removes</strong> them from the stash list.</p>
</li>
<li><p><code>git stash apply</code> restores your changes but <strong>keeps</strong> them in the stash list for future use.</p>
</li>
</ul>
<h2 id="heading-how-to-undo-commits-safely-with-git-revert">How to Undo Commits Safely with <code>git revert</code></h2>
<p>Now let’s talk about <code>git revert</code>. The <code>git revert</code> command is used to undo the changes made in a previous commit – but instead of deleting that old commit, it creates a <strong>new</strong> one that reverses those changes. In other words, it cancels out the effects of a previous commit while keeping the project history completely clean and traceable.</p>
<p>That’s why it’s called “revert”: because it doesn’t delete any commit. Instead, it creates a new commit that brings the project back to its previous correct state. Simply put, <code>git revert</code> means fixing an old mistake without erasing it.</p>
<p>For example, imagine you accidentally added too much salt while cooking. Instead of throwing the whole dish away, you adjust the flavor by adding some extra ingredients to balance the saltiness. Similarly, <code>git revert</code> doesn’t delete the faulty commit – it corrects it through a new one.</p>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443720093/f7506aa8-e16b-4566-a0c8-f497e195b783.gif" alt="Git Revert Command" width="1138" height="640" loading="lazy"></p>
<p>To revert something, you need its commit ID. Suppose in the file <code>three.txt</code>, you added the line:</p>
<pre><code class="lang-text">hello three
</code></pre>
<p>Then you run:</p>
<pre><code class="lang-bash">git add .
git commit -m <span class="hljs-string">"hello three"</span>
</code></pre>
<p>Now, if you check the log:</p>
<pre><code class="lang-bash">git <span class="hljs-built_in">log</span> --oneline
</code></pre>
<p>you’ll see there are 10 commits in total. You realize that the <code>"hello three"</code> commit introduced a bug and you want to remove it. Before that, copy the commit ID of <code>"hello three"</code> and then run:</p>
<pre><code class="lang-bash">git revert &lt;that-commit-id&gt;
</code></pre>
<p>After running the command, you’ll see a prompt asking for a commit message. You can type a custom message or simply keep the default one and exit (for example, by using <code>- wq</code> in Vim). Once you do that, the changes from <code>"hello three"</code> will be undone. Check the logs again:</p>
<pre><code class="lang-bash">git <span class="hljs-built_in">log</span> --oneline
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443740518/c8ef43d8-78e8-4afe-8424-5a24d0987640.gif" alt="Git Revert Specific Commit" width="1138" height="640" loading="lazy"></p>
<p>You’ll notice there’s a new commit added specifically for the revert. At this point, you might be reminded of <code>git reset</code>. The main difference between <code>git reset</code> and <code>git revert</code> is:</p>
<ul>
<li><p><code>git reset</code> can take you back to a specific commit and discard all commits after that point, <strong>without creating any new commit</strong>.</p>
</li>
<li><p><code>git revert</code> removes the changes from a specific commit by <strong>creating a new commit</strong> that reverses it.</p>
</li>
</ul>
<p>If your project is on GitHub or any remote repository, other contributors can also see the revert commit, ensuring clarity and preventing confusion.</p>
<p>Another key point is that if you check the logs after a reset, there’s no record of the removed commits. But when you use revert, you’ll clearly see an additional commit indicating that a revert took place.</p>
<h2 id="heading-how-to-keep-history-clean-with-git-rebase">How to Keep History Clean with <code>git rebase</code></h2>
<p>Now let’s talk about Git Rebase. Imagine you’re starting to work on a new feature. You create a new branch called <code>feature</code> by checking out from the <code>main</code> branch. You begin developing the new feature, making changes bit by bit, and committing your progress as you go. Meanwhile, another developer adds more updates to the <code>main</code> branch for production. Now you want to include those latest updates from <code>main</code> into your <code>feature</code> branch. What can you do?</p>
<p>There are several ways to handle this. As we’ve seen before, one option is to merge the <code>main</code> branch into your <code>feature</code> branch. If you do that, Git creates a new <strong>merge commit</strong>, and all the latest updates from <code>main</code> are merged into your <code>feature</code> branch.</p>
<p>But merging always creates an additional commit – you can see it clearly if you run <code>git log</code>. Some developers find these extra merge commits a bit messy. If you continue merging multiple times, your commit history can look cluttered.</p>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443759550/d074c631-1e65-4ef3-a007-e2d7665eccd7.gif" alt="Git Rebase Command" width="1138" height="640" loading="lazy"></p>
<p>In such cases, a better solution is to use <strong>Git Rebase</strong>. When you perform a rebase, the base of your <code>feature</code> branch changes. That means if you rebase onto <code>main</code>, all the new commits from <code>main</code> are applied directly into your <code>feature</code> branch, and then your <code>feature</code> branch commits are reapplied on top of them. While your <code>main</code> branch’s code content remains the same, the commit history becomes much cleaner and more linear – and you can easily verify this using <code>git log</code>.</p>
<p>Let’s understand this with an example. Create a new branch called <code>feature</code> from <code>main</code>:</p>
<pre><code class="lang-bash">git branch feature
git checkout feature
</code></pre>
<p>You’re now inside the <code>feature</code> branch. Open <code>one.txt</code> and add the line:</p>
<pre><code class="lang-text">adding dark mode functionality
</code></pre>
<p>Then stage and commit:</p>
<pre><code class="lang-bash">git add .
git commit -m <span class="hljs-string">"adding dark mode functionality"</span>
</code></pre>
<p>Now switch back to the <code>main</code> branch:</p>
<pre><code class="lang-bash">git checkout main
</code></pre>
<p>You’re now in the <code>main</code> branch. Create a new file called <code>two.txt</code> and write:</p>
<pre><code class="lang-text">adding dark mode ui
</code></pre>
<p>Then stage and commit:</p>
<pre><code class="lang-bash">git add .
git commit -m <span class="hljs-string">"adding dark mode ui"</span>
</code></pre>
<p>Now the <code>main</code> branch has a new feature – “dark mode ui”. You want that same “dark mode ui” update to appear in your <code>feature</code> branch as well. Switch back to your <code>feature</code> branch:</p>
<pre><code class="lang-bash">git checkout feature
</code></pre>
<p>Your goal is to bring the latest updates from the <code>main</code> branch into the <code>feature</code> branch. But this time, we’ll do it using <strong>rebase</strong>.</p>
<p>To perform a Git rebase, you need to be on the branch you want to rebase, and then specify the branch from which you want to bring the changes. For example, if you’re currently on the <code>feature</code> branch and want to bring in the changes from <code>main</code>, run:</p>
<pre><code class="lang-bash">git rebase main
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443782936/9dbfa229-e02a-40f3-8f91-14fcbf4c858e.gif" alt="Git Rebase Main into Feature" width="1138" height="640" loading="lazy"></p>
<p>Once you run this command, the rebase completes, and the “dark mode ui” update from the <code>main</code> branch appears in your <code>feature</code> branch.</p>
<p>Here’s what happens behind the scenes when you use rebase:</p>
<ol>
<li><p>Git identifies the most recent common commit shared between your current branch (<code>feature</code>) and the branch you’re rebasing onto (<code>main</code>).</p>
</li>
<li><p>All the commits in your <code>feature</code> branch that come after that common commit are temporarily set aside.</p>
</li>
<li><p>Git applies all the new commits from the <code>main</code> branch into your <code>feature</code> branch.</p>
</li>
<li><p>Finally, it reapplies the saved commits from the <code>feature</code> branch on top of those <code>main</code> commits, one by one.</p>
</li>
</ol>
<p>The result is a clean, linear commit history that’s much tidier than what you get with merging. You can easily see this difference by running <code>git log</code>.</p>
<p>Just keep in mind that <code>git rebase</code> is powerful. So it’s not recommended to use it on <strong>public repositories</strong> or branches where multiple developers are working together. If you must use it, you should always inform your team beforehand. Otherwise, it can cause serious issues.</p>
<p>The reason is that rebase <strong>rewrites existing commit history</strong> – even the commit hashes (IDs) change. So, if someone else is working on the same branch, your rebased commits won’t match their local copies anymore, and they won’t be able to pull or sync normally.</p>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443802090/97b145e9-7b86-4106-99fe-683ef8d5025b.gif" alt="Git Rebase Warning" width="1138" height="640" loading="lazy"></p>
<p>So before using rebase, make sure you fully understand where you’re applying it and whether it could cause problems for your collaborators. It’s perfectly safe to use rebase on your local or personal branches where only you’re working – just avoid rewriting commits that already exist on a shared remote branch.</p>
<h2 id="heading-how-to-collaborate-on-github-with-pull-requests">How to Collaborate on GitHub with Pull Requests</h2>
<p>Before wrapping up, let’s discuss one last important topic: the <strong>Pull Request</strong>. When working with Git and GitHub, the term “Pull Request,” often shortened as “PR,” comes up frequently.</p>
<p>A Pull Request is essentially a request you make to merge your changes into another branch – usually the <code>main</code> branch. It’s a way of saying, “I’ve made some changes in my branch. Please review them, and if everything looks good, merge them into the main branch.”</p>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443820127/5ea7b5ce-a06d-42d3-88d7-da5e818210dc.gif" alt="GitHub Pull Request" width="1138" height="640" loading="lazy"></p>
<p>In other words, you typically don’t make changes directly to someone else’s repository. When you finish your work in your own branch, you create a Pull Request to ask for permission to merge your code into the main repository. That’s what a Pull Request is.</p>
<p>Go back to your <code>git-journey</code> repository on GitHub. By now, you’ve already pushed your <code>main</code>, <code>staging</code>, and <code>development</code> branches. At the top of the GitHub page, you’ll see several tabs: <strong>Code</strong>, <strong>Issues</strong>, <strong>Pull requests</strong>, and <strong>Actions</strong>.</p>
<p>Click on the <strong>Pull requests</strong> tab. Here, you’ll see a big green button labeled <strong>New pull request</strong>. This is where you can say, “I want to merge the changes from this branch into another branch.”</p>
<p>Once you click New pull request, GitHub shows you two dropdown menus:</p>
<ul>
<li><p><strong>base</strong>: the branch where you want to merge the changes (select <code>main</code> here).</p>
</li>
<li><p><strong>compare</strong>: the branch from which you want to bring the changes (select <code>development</code>).</p>
</li>
</ul>
<p>In other words, you’re saying, “I’ve made some updates in the <code>development</code> branch, and now I want those updates to be merged into the <code>main</code> branch.” GitHub automatically shows a detailed comparison: which files have been modified, which lines have been added, and which ones have been removed, with everything clearly visible. If everything looks good, scroll down and click <strong>Create pull request</strong>.</p>
<p>Give your PR a title, such as:</p>
<pre><code class="lang-text">Merge development updates into main
</code></pre>
<p>In the description box, you can write something like:</p>
<pre><code class="lang-text">This PR adds the latest updates and fixes from development to main.
</code></pre>
<p>Then click <strong>Create pull request</strong> to submit it. Now, if you go back to the <strong>Pull requests</strong> tab, you’ll see your newly created PR:</p>
<pre><code class="lang-text">development → main
</code></pre>
<p>Click on it, and you’ll find three sections:</p>
<ul>
<li><p><strong>Conversation:</strong> where you and your teammates can discuss or comment on the changes.</p>
</li>
<li><p><strong>Commits</strong>: which lists all the commits included in this PR.</p>
</li>
<li><p><strong>Files changed</strong>: which shows exactly what changes were made in which files.</p>
</li>
</ul>
<p>If everything looks good after review, click the green <strong>Merge pull request</strong> button at the top, and then confirm by clicking <strong>Confirm merge</strong>. Once it’s done, GitHub displays a message:</p>
<pre><code class="lang-text">Pull request successfully merged and closed.
</code></pre>
<p><img src="https://cdn.hashnode.com/res/hashnode/image/upload/v1765443840494/12e57fd1-64fb-412d-913d-599edebf1132.gif" alt="Pull Request Example" width="1138" height="640" loading="lazy"></p>
<p>That means all the updates from the <code>development</code> branch have now been successfully merged into <code>main</code>.</p>
<p>This is how Pull Requests make code management much easier. Every change gets reviewed first and then merged into <code>main</code>. As a result, the main branch stays stable, and the entire team can collaborate safely and efficiently.</p>
<h2 id="heading-git-amp-github-concise-summary">Git &amp; GitHub – Concise Summary</h2>
<h3 id="heading-git-vs-github-1">Git vs GitHub</h3>
<ul>
<li><p><strong>Git</strong>: Local version control tool that tracks every change to your files, lets you keep multiple versions, and roll back any time.</p>
</li>
<li><p><strong>GitHub</strong>: Online hosting platform for Git repositories that acts like a central “code server” so teams can share, review, and collaborate.</p>
</li>
<li><p>Other Git hosts exist (GitLab, Bitbucket), but GitHub is the most widely used, especially for open source.</p>
</li>
</ul>
<h3 id="heading-core-git-architecture-amp-workflow">Core Git Architecture &amp; Workflow</h3>
<ul>
<li><p>Work happens in the <strong>working directory</strong> (your project folder).</p>
</li>
<li><p>When changes are ready, you move them to the <strong>staging area</strong> with <code>git add</code>.</p>
</li>
<li><p>You permanently record a version in the <strong>local repository</strong> with <code>git commit</code>.</p>
</li>
<li><p>The <strong>remote repository</strong> (for example, on GitHub) is a copy of your repo stored in the cloud for backup and collaboration.</p>
</li>
</ul>
<p>Basic flow:</p>
<ol>
<li><p>Edit files in the working directory.</p>
</li>
<li><p>Stage changes: <code>git add &lt;files&gt;</code> or <code>git add .</code></p>
</li>
<li><p>Commit: <code>git commit -m "message"</code></p>
</li>
<li><p>Sync with remote: <code>git push</code> / <code>git pull</code></p>
</li>
</ol>
<h3 id="heading-getting-started">Getting Started</h3>
<ul>
<li><p>Install Git from the official site: <a target="_blank" href="https://git-scm.com/downloads"><code>https://git-scm.com/downloads</code></a>.</p>
</li>
<li><p>Check installation: <code>git --version</code>.</p>
</li>
<li><p>Configure identity (needed before first commit):</p>
<ul>
<li><p><code>git config --global</code> <a target="_blank" href="http://user.name"><code>user.name</code></a> <code>"Your Name"</code></p>
</li>
<li><p><code>git config --global</code> <a target="_blank" href="http://user.email"><code>user.email</code></a> <code>"</code><a target="_blank" href="mailto:you@example.com"><code>you@example.com</code></a><code>"</code></p>
</li>
</ul>
</li>
<li><p>Initialize a repo in a folder: <code>git init</code>.</p>
</li>
<li><p>Or clone an existing repo from GitHub: <code>git clone &lt;repo-url&gt;</code>.</p>
</li>
</ul>
<h3 id="heading-seeing-amp-moving-changes">Seeing &amp; Moving Changes</h3>
<ul>
<li><p>Check what changed and what’s staged: <code>git status</code>.</p>
</li>
<li><p>Stage changes:</p>
<ul>
<li><p><code>git add --all</code> / <code>git add -A</code>: stage everything (adds, changes, deletions).</p>
</li>
<li><p><code>git add .</code>: stage changes only in the current directory.</p>
</li>
<li><p><code>git add &lt;file&gt;</code> or <code>git add *.txt</code>: stage specific files or patterns.</p>
</li>
</ul>
</li>
<li><p>Unstage everything (but keep edits in files): <code>git reset</code>.</p>
</li>
<li><p>Save staged changes as a commit: <code>git commit -m "message"</code>.</p>
</li>
<li><p>View commit history:</p>
<ul>
<li><p>Full: <code>git log</code></p>
</li>
<li><p>Compact: <code>git log --oneline</code></p>
</li>
</ul>
</li>
</ul>
<h3 id="heading-deleting-restoring-amp-undoing">Deleting, Restoring, &amp; Undoing</h3>
<ul>
<li><p>Delete a tracked file and stage the deletion: <code>git rm &lt;file&gt;</code>.</p>
<ul>
<li><p>Force delete changed file: <code>git rm -f &lt;file&gt;</code>.</p>
</li>
<li><p>Stop tracking but keep file: <code>git rm --cached &lt;file&gt;</code>.</p>
</li>
</ul>
</li>
<li><p>Undo staged changes only: <code>git reset</code>.</p>
</li>
<li><p>Reset everything (including working directory) to last commit: <code>git reset --hard</code>.</p>
</li>
<li><p>Restore file content back to last commit:</p>
<ul>
<li><p>Single file: <code>git restore &lt;file&gt;</code></p>
</li>
<li><p>All files: <code>git restore .</code></p>
</li>
</ul>
</li>
<li><p>Undo a <strong>commit</strong> safely (create a new “fix” commit):</p>
<ul>
<li><code>git revert &lt;commit-id&gt;</code></li>
</ul>
</li>
<li><p>Move HEAD and history back to an earlier commit (dangerous on shared branches):</p>
<ul>
<li>Example: <code>git reset HEAD~</code> (undo last commit locally).</li>
</ul>
</li>
</ul>
<h3 id="heading-branching-merging-amp-conflicts">Branching, Merging, &amp; Conflicts</h3>
<ul>
<li><p>A <strong>branch</strong> is an independent line of development (for example, <code>main</code>, <code>development</code>, <code>staging</code>, <code>feature</code>).</p>
</li>
<li><p>List branches: <code>git branch</code>.</p>
</li>
<li><p>Create branch: <code>git branch development</code>.</p>
</li>
<li><p>Switch branch: <code>git checkout development</code> (or <code>git switch development</code> in newer Git).</p>
</li>
<li><p>Typical workflow: keep <code>main</code> stable, build new features on separate branches, then merge back.</p>
</li>
<li><p>Merge another branch into the current one: <code>git merge &lt;branch-name&gt;</code>.</p>
</li>
<li><p>If the same lines changed differently in two branches, you get a <strong>merge conflict</strong>:</p>
<ul>
<li><p>Git marks conflicts in the file with <code>&lt;&lt;&lt;&lt;&lt;&lt;&lt;</code>, <code>=======</code>, <code>&gt;&gt;&gt;&gt;&gt;&gt;&gt;</code>.</p>
</li>
<li><p>You manually edit to the correct final content, then:</p>
<ul>
<li><p><code>git add .</code></p>
</li>
<li><p><code>git commit -m "merge conflict resolved"</code></p>
</li>
</ul>
</li>
</ul>
</li>
</ul>
<h3 id="heading-navigating-amp-comparing-history">Navigating &amp; Comparing History</h3>
<ul>
<li><p>Jump to an old commit (read-only “detached HEAD” state): <code>git checkout &lt;commit-id&gt;</code></p>
</li>
<li><p>Return to the latest <code>main</code>: <code>git checkout main</code>.</p>
</li>
<li><p>Compare two commits: <code>git diff &lt;old-id&gt; &lt;new-id&gt;</code> – shows what changed between them.</p>
</li>
</ul>
<h3 id="heading-working-with-remotes-github">Working with Remotes (GitHub)</h3>
<ul>
<li><p>Push local branch to remote: <code>git push origin &lt;branch&gt;</code>.</p>
</li>
<li><p>Fetch latest state from remote <strong>without</strong> updating your working files: <code>git fetch</code></p>
<ul>
<li>Then merge if needed: <code>git merge origin/main</code></li>
</ul>
</li>
<li><p>Pull and merge in one step: <code>git pull</code> (equivalent to <code>fetch + merge</code>).</p>
</li>
</ul>
<h3 id="heading-temporarily-shelving-work-with-git-stash">Temporarily Shelving Work with <code>git stash</code></h3>
<ul>
<li><p>Use <code>git stash</code> when you have uncommitted work but need to switch branches.</p>
</li>
<li><p><code>git stash</code>: saves current changes and cleans your working directory.</p>
</li>
<li><p>Switch branches, do other work, then come back and restore:</p>
<ul>
<li><p><code>git stash pop</code>: restore and remove from stash list.</p>
</li>
<li><p><code>git stash apply</code>: restore but keep entry in the stash.</p>
</li>
</ul>
</li>
<li><p>See all stashes: <code>git stash list</code>.</p>
</li>
<li><p>Remove a stash explicitly: <code>git stash drop</code>.</p>
</li>
</ul>
<h3 id="heading-keeping-history-clean-with-git-rebase">Keeping History Clean with <code>git rebase</code></h3>
<ul>
<li><p><code>git rebase &lt;branch&gt;</code> replays your current branch’s commits on top of another branch, creating a cleaner, linear history.</p>
</li>
<li><p>Safe on your <strong>own</strong> local branches, but dangerous on shared/public branches because it rewrites commit history (IDs change).</p>
</li>
<li><p>Common pattern: on <code>feature</code> branch, run <code>git rebase main</code> to bring latest <code>main</code> changes under your feature commits.</p>
</li>
</ul>
<h3 id="heading-collaboration-with-pull-requests-prs">Collaboration with Pull Requests (PRs)</h3>
<ul>
<li><p>On GitHub, you usually:</p>
<ol>
<li><p>Push your feature branch.</p>
</li>
<li><p>Open a <strong>Pull Request</strong> (PR) to request merging into <code>main</code> (or another base branch).</p>
</li>
<li><p>Teammates review code, discuss in comments, and approve.</p>
</li>
<li><p>The PR is merged (and usually closed) once accepted.</p>
</li>
</ol>
</li>
<li><p>PRs keep <code>main</code> stable and make reviews and history clearer.</p>
</li>
</ul>
<h3 id="heading-big-picture-takeaways">Big Picture Takeaways</h3>
<ul>
<li><p>Git tracks every change, lets you move safely between versions, and protects you from losing work.</p>
</li>
<li><p>GitHub (or other remotes) adds backup, sharing, and collaboration.</p>
</li>
<li><p>Most day‑to‑day work is based on a small set of commands: <code>git status</code>, <code>git add</code>, <code>git commit</code>, <code>git push</code>, <code>git pull</code>, <code>git branch</code>, <code>git checkout</code>, <code>git merge</code>, <code>git log</code>.</p>
</li>
<li><p>Advanced commands like <code>git reset</code>, <code>git restore</code>, <code>git revert</code>, <code>git stash</code>, and <code>git rebase</code> give you powerful ways to undo mistakes and keep history clean.</p>
</li>
</ul>
<h2 id="heading-final-words">Final Words</h2>
<p>This tutorial on Git and GitHub has walked through the essential, day-to-day concepts in a step-by-step, practical way. It’s especially helpful for those who are just getting started. If you’ve always felt a bit intimidated or confused about using Git for the first time, this guide was created with you in mind.</p>
<p>If you found the information here valuable, feel free to share it with others who might benefit from it. I’d really appreciate your thoughts – mention me on X <a target="_blank" href="https://x.com/sumit_analyzen">@sumit_analyzen</a> or on Facebook <a target="_blank" href="https://www.facebook.com/sumit.analyzen">@sumit.analyzen</a>, <a target="_blank" href="https://www.youtube.com/@logicBaseLabs">watch</a> my coding tutorials, or simply <a target="_blank" href="https://www.linkedin.com/in/sumitanalyzen/">connect with me</a> on LinkedIn. You can also checkout my official website <a target="_blank" href="https://www.sumitsaha.me/">sumitsaha.me</a> for more details about me.</p>
 ]]>
                </content:encoded>
            </item>
        
            <item>
                <title>
                    <![CDATA[ Git & GitHub Crash Course for Beginners ]]>
                </title>
                <description>
                    <![CDATA[ Git is important for any developer. We just posted a course that will help you learn Git and GitHub from scratch with clear examples, real workflows, branching, merging, stashing, rebase, pull requests, and more. This course is great for beginners wh... ]]>
                </description>
                <link>https://www.freecodecamp.org/news/git-and-github-crash-course-for-beginners/</link>
                <guid isPermaLink="false">6931ef1a5feb2860f3beafd6</guid>
                
                    <category>
                        <![CDATA[ GitHub ]]>
                    </category>
                
                    <category>
                        <![CDATA[ youtube ]]>
                    </category>
                
                    <category>
                        <![CDATA[ Git ]]>
                    </category>
                
                <dc:creator>
                    <![CDATA[ Beau Carnes ]]>
                </dc:creator>
                <pubDate>Thu, 04 Dec 2025 20:29:14 +0000</pubDate>
                <media:content url="https://cdn.hashnode.com/res/hashnode/image/upload/v1764880033392/03198f4c-c7c0-4ba1-a383-24c546a418cf.jpeg" medium="image" />
                <content:encoded>
                    <![CDATA[ <p>Git is important for any developer.</p>
<p>We just posted a course that will help you learn Git and GitHub from scratch with clear examples, real workflows, branching, merging, stashing, rebase, pull requests, and more. This course is great for beginners who want strong foundations. Sumit Saha developed this course.</p>
<p>Here are the things you will learn in this video:</p>
<ul>
<li><p>The difference between Git and GitHub in the simplest way</p>
</li>
<li><p>How Git tracks your work using the working directory, staging area, and repository</p>
</li>
<li><p>Core Git commands: add, commit, status, log, reset, restore, rm</p>
</li>
<li><p>How to work with branches, merge updates, and fix merge conflicts</p>
</li>
<li><p>How to push, pull, and sync your code with GitHub</p>
</li>
<li><p>Using stash, revert, and rebase to handle real-world workflows</p>
</li>
<li><p>How pull requests work and why teams use them</p>
</li>
</ul>
<p>Watch the full course on the freeCodeCamp.org YouTube channel (1-hour watch).</p>
<div class="embed-wrapper">
        <iframe width="560" height="315" src="https://www.youtube.com/embed/mAFoROnOfHs" style="aspect-ratio: 16 / 9; width: 100%; height: auto;" title="YouTube video player" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen="" loading="lazy"></iframe></div>
 ]]>
                </content:encoded>
            </item>
        
    </channel>
</rss>
