netlify · JakeChampion · Mar 17, 2025 · Mar 5, 2025
diff --git a/src/lib/purge_cache.test.ts b/src/lib/purge_cache.test.ts
@@ -58,6 +58,106 @@ test('Calls the purge API endpoint and returns `undefined` if the operation was
  expect(mockAPI.fulfilled).toBeTruthy()
 })

+test('Does not default the deploy_alias field to process.env.NETLIFY_BRANCH if supplied in the options', async () => {
+  const mockSiteID = '123456789'
+  const mockToken = '1q2w3e4r5t6y7u8i9o0p'
+
+  process.env.NETLIFY_PURGE_API_TOKEN = mockToken
+  process.env.SITE_ID = mockSiteID
+  process.env.NETLIFY_BRANCH = 'main'
+
+  const mockAPI = new MockFetch().post({
+    body: (payload: string) => {
+      const data = JSON.parse(payload)
+
+      expect(data.site_id).toBe(mockSiteID)
+      expect(data.deploy_alias).toBe('test')
+    },
+    headers: { Authorization: `Bearer ${mockToken}` },
+    method: 'post',
+    response: new Response(null, { status: 202 }),
+    url: `https://api.netlify.com/api/v1/purge`,
+  })
+  // eslint-disable-next-line unicorn/consistent-function-scoping
+  const myFunction = async () => {
+    await purgeCache({ deployAlias: 'test' })
+  }
+
+  globalThis.fetch = mockAPI.fetcher
+
+  const response = await invokeLambda(myFunction)
+
+  expect(response).toBeUndefined()
+  expect(mockAPI.fulfilled).toBeTruthy()
+})
+
+test('Defaults the deploy_alias field to process.env.NETLIFY_BRANCH if not running locally', async () => {
+  const mockSiteID = '123456789'
+  const mockToken = '1q2w3e4r5t6y7u8i9o0p'
+
+  process.env.NETLIFY_PURGE_API_TOKEN = mockToken
+  process.env.SITE_ID = mockSiteID
+  process.env.NETLIFY_BRANCH = 'main'
+
+  const mockAPI = new MockFetch().post({
+    body: (payload: string) => {
+      const data = JSON.parse(payload)
+
+      expect(data.site_id).toBe(mockSiteID)
+      expect(data.deploy_alias).toBe(process.env.NETLIFY_BRANCH)
+    },
+    headers: { Authorization: `Bearer ${mockToken}` },
+    method: 'post',
+    response: new Response(null, { status: 202 }),
+    url: `https://api.netlify.com/api/v1/purge`,
+  })
+  // eslint-disable-next-line unicorn/consistent-function-scoping
+  const myFunction = async () => {
+    await purgeCache()
+  }
+
+  globalThis.fetch = mockAPI.fetcher
+
+  const response = await invokeLambda(myFunction)
+
+  expect(response).toBeUndefined()
+  expect(mockAPI.fulfilled).toBeTruthy()
+})
+
+test('Does not default the deploy_alias field to process.env.NETLIFY_BRANCH when running locally', async () => {
+  const mockSiteID = '123456789'
+  const mockToken = '1q2w3e4r5t6y7u8i9o0p'
+
+  process.env.NETLIFY_PURGE_API_TOKEN = mockToken
+  process.env.SITE_ID = mockSiteID
+  process.env.NETLIFY_LOCAL = 'true'
+  process.env.NETLIFY_BRANCH = 'main'
+
+  const mockAPI = new MockFetch().post({
+    body: (payload: string) => {
+      const data = JSON.parse(payload)
+
+      expect(data.site_id).toBe(mockSiteID)
+      expect(data.deploy_alias).toBeUndefined()
+    },
+    headers: { Authorization: `Bearer ${mockToken}` },
+    method: 'post',
+    response: new Response(null, { status: 202 }),
+    url: `https://api.netlify.com/api/v1/purge`,
+  })
+  // eslint-disable-next-line unicorn/consistent-function-scoping
+  const myFunction = async () => {
+    await purgeCache()
+  }
+
+  globalThis.fetch = mockAPI.fetcher
+
+  const response = await invokeLambda(myFunction)
+
+  expect(response).toBeUndefined()
+  expect(mockAPI.fulfilled).toBeTruthy()
+})
+
 test('Throws an error if the API response does not have a successful status code, using the response body as part of the error message', async () => {
  if (!hasFetchAPI) {
    console.warn('Skipping test requires the fetch API')

diff --git a/src/lib/purge_cache.ts b/src/lib/purge_cache.ts
@@ -48,8 +48,14 @@ export const purgeCache = async (options: PurgeCacheOptions = {}) => {

  const payload: PurgeAPIPayload = {
    cache_tags: options.tags,
-    deploy_alias: options.deployAlias,
  }
+
+  if ('deployAlias' in options) {
+    payload.deploy_alias = options.deployAlias
+  } else if (!env.NETLIFY_LOCAL) {
+    payload.deploy_alias = env.NETLIFY_BRANCH
+  }
+
  const token = env.NETLIFY_PURGE_API_TOKEN || options.token

  if (env.NETLIFY_LOCAL && !token) {