Merge 6b8be4cb30 into cbb722410c

Add a scenario where it is necessary to push a commit to a pull request.

.github/workflows/publish-immutable-actions.yml

@@ -0,0 +1,20 @@
+name: 'Publish Immutable Action Version'
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+      packages: write
+
+    steps:
+      - name: Checking out
+        uses: actions/checkout@v4
+      - name: Publish
+        id: publish
+        uses: actions/publish-immutable-action@0.0.3

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## v4.2.2
+* `url-helper.ts` now leverages well-known environment variables by @jww3 in https://github.com/actions/checkout/pull/1941
+* Expand unit test coverage for `isGhes` by @jww3 in https://github.com/actions/checkout/pull/1946
+
+## v4.2.1
+* Check out other refs/* by commit if provided, fall back to ref by @orhantoy in https://github.com/actions/checkout/pull/1924
+
+## v4.2.0
+
+* Add Ref and Commit outputs by @lucacome in https://github.com/actions/checkout/pull/1180
+* Dependency updates by @dependabot- https://github.com/actions/checkout/pull/1777, https://github.com/actions/checkout/pull/1872
+
 ## v4.1.7
 * Bump the minor-npm-dependencies group across 1 directory with 4 updates by @dependabot in https://github.com/actions/checkout/pull/1739
 * Bump actions/checkout from 3 to 4 by @dependabot in https://github.com/actions/checkout/pull/1697

README.md

@@ -29,6 +29,11 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
     # Otherwise, uses the default branch.
     ref: ''
 
+    # Indicates whether to checkout the default repository branch if the requested ref
+    # does not exist
+    # Default: false
+    default-branch-checkout: ''
+
     # Personal access token (PAT) used to fetch the repository. The PAT is configured
     # with the local git config, which enables your scripts to run authenticated git
     # commands. The post-job step removes the PAT.
@@ -143,6 +148,7 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
 - [Checkout pull request HEAD commit instead of merge commit](#Checkout-pull-request-HEAD-commit-instead-of-merge-commit)
 - [Checkout pull request on closed event](#Checkout-pull-request-on-closed-event)
 - [Push a commit using the built-in token](#Push-a-commit-using-the-built-in-token)
+- [Push a commit to a PR using the built-in token](#Push-a-commit-to-a-PR-using-the-built-in-token)
 
 ## Fetch only the root files
 
@@ -211,7 +217,7 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
     repository: my-org/my-tools
     path: my-tools
 ```
-> - If your secondary repository is private you will need to add the option noted in [Checkout multiple repos (private)](#Checkout-multiple-repos-private)
+> - If your secondary repository is private or internal you will need to add the option noted in [Checkout multiple repos (private)](#Checkout-multiple-repos-private)
 
 ## Checkout multiple repos (nested)
 
@@ -225,7 +231,7 @@ Please refer to the [release page](https://github.com/actions/checkout/releases/
     repository: my-org/my-tools
     path: my-tools
 ```
-> - If your secondary repository is private you will need to add the option noted in [Checkout multiple repos (private)](#Checkout-multiple-repos-private)
+> - If your secondary repository is private or internal you will need to add the option noted in [Checkout multiple repos (private)](#Checkout-multiple-repos-private)
 
 ## Checkout multiple repos (private)
 
@@ -288,6 +294,31 @@ jobs:
 ```
 *NOTE:* The user email is `{user.id}+{user.login}@users.noreply.github.com`. See users API: https://api.github.com/users/github-actions%5Bbot%5D
 
+## Push a commit to a PR using the built-in token
+
+In a pull request trigger, `ref` is required as GitHub Actions checks out in detached HEAD mode, meaning it doesn’t check out your branch by default.
+
+```yaml
+on: pull_request
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.head_ref }}
+      - run: |
+          date > generated.txt
+          # Note: the following account information will not work on GHES
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add .
+          git commit -m "generated"
+          git push
+```
+*NOTE:* The user email is `{user.id}+{user.login}@users.noreply.github.com`. See users API: https://api.github.com/users/github-actions%5Bbot%5D
+
+
 # License
 
 The scripts and documentation in this project are released under the [MIT License](LICENSE)

__test__/git-auth-helper.test.ts

@@ -815,6 +815,7 @@ async function setup(testName: string): Promise<void> {
     nestedSubmodules: false,
     persistCredentials: true,
     ref: 'refs/heads/main',
+    defaultBranchCheckout: false,
     repositoryName: 'my-repo',
     repositoryOwner: 'my-org',
     repositoryPath: '',

__test__/input-helper.test.ts

@@ -80,6 +80,7 @@ describe('input-helper tests', () => {
     expect(settings.commit).toBeTruthy()
     expect(settings.commit).toBe('1234567890123456789012345678901234567890')
     expect(settings.filter).toBe(undefined)
+    expect(settings.defaultBranchCheckout).toBe(false)
     expect(settings.sparseCheckout).toBe(undefined)
     expect(settings.sparseCheckoutConeMode).toBe(true)
     expect(settings.fetchDepth).toBe(1)

__test__/ref-helper.test.ts

@@ -77,6 +77,16 @@ describe('ref-helper tests', () => {
     expect(checkoutInfo.startPoint).toBeFalsy()
   })
 
+  it('getCheckoutInfo refs/ without commit', async () => {
+    const checkoutInfo = await refHelper.getCheckoutInfo(
+      git,
+      'refs/non-standard-ref',
+      ''
+    )
+    expect(checkoutInfo.ref).toBe('refs/non-standard-ref')
+    expect(checkoutInfo.startPoint).toBeFalsy()
+  })
+
   it('getCheckoutInfo unqualified branch only', async () => {
     git.branchExists = jest.fn(async (remote: boolean, pattern: string) => {
       return true

__test__/url-helper.test.ts

@@ -0,0 +1,92 @@
+import * as urlHelper from '../src/url-helper'
+
+describe('getServerUrl tests', () => {
+  it('basics', async () => {
+    // Note that URL::toString will append a trailing / when passed just a domain name ...
+    expect(urlHelper.getServerUrl().toString()).toBe('https://github.com/')
+    expect(urlHelper.getServerUrl(' ').toString()).toBe('https://github.com/')
+    expect(urlHelper.getServerUrl('   ').toString()).toBe('https://github.com/')
+    expect(urlHelper.getServerUrl('http://contoso.com').toString()).toBe(
+      'http://contoso.com/'
+    )
+    expect(urlHelper.getServerUrl('https://contoso.com').toString()).toBe(
+      'https://contoso.com/'
+    )
+    expect(urlHelper.getServerUrl('https://contoso.com/').toString()).toBe(
+      'https://contoso.com/'
+    )
+
+    // ... but can't make that same assumption when passed an URL that includes some deeper path.
+    expect(urlHelper.getServerUrl('https://contoso.com/a/b').toString()).toBe(
+      'https://contoso.com/a/b'
+    )
+  })
+})
+
+describe('isGhes tests', () => {
+  const pristineEnv = process.env
+
+  beforeEach(() => {
+    jest.resetModules()
+    process.env = {...pristineEnv}
+  })
+
+  afterAll(() => {
+    process.env = pristineEnv
+  })
+
+  it('basics', async () => {
+    delete process.env['GITHUB_SERVER_URL']
+    expect(urlHelper.isGhes()).toBeFalsy()
+    expect(urlHelper.isGhes('https://github.com')).toBeFalsy()
+    expect(urlHelper.isGhes('https://contoso.ghe.com')).toBeFalsy()
+    expect(urlHelper.isGhes('https://test.github.localhost')).toBeFalsy()
+    expect(urlHelper.isGhes('https://src.onpremise.fabrikam.com')).toBeTruthy()
+  })
+
+  it('returns false when the GITHUB_SERVER_URL environment variable is not defined', async () => {
+    delete process.env['GITHUB_SERVER_URL']
+    expect(urlHelper.isGhes()).toBeFalsy()
+  })
+
+  it('returns false when the GITHUB_SERVER_URL environment variable is set to github.com', async () => {
+    process.env['GITHUB_SERVER_URL'] = 'https://github.com'
+    expect(urlHelper.isGhes()).toBeFalsy()
+  })
+
+  it('returns false when the GITHUB_SERVER_URL environment variable is set to a GitHub Enterprise Cloud-style URL', async () => {
+    process.env['GITHUB_SERVER_URL'] = 'https://contoso.ghe.com'
+    expect(urlHelper.isGhes()).toBeFalsy()
+  })
+
+  it('returns false when the GITHUB_SERVER_URL environment variable has a .localhost suffix', async () => {
+    process.env['GITHUB_SERVER_URL'] = 'https://mock-github.localhost'
+    expect(urlHelper.isGhes()).toBeFalsy()
+  })
+
+  it('returns true when the GITHUB_SERVER_URL environment variable is set to some other URL', async () => {
+    process.env['GITHUB_SERVER_URL'] = 'https://src.onpremise.fabrikam.com'
+    expect(urlHelper.isGhes()).toBeTruthy()
+  })
+})
+
+describe('getServerApiUrl tests', () => {
+  it('basics', async () => {
+    expect(urlHelper.getServerApiUrl()).toBe('https://api.github.com')
+    expect(urlHelper.getServerApiUrl('https://github.com')).toBe(
+      'https://api.github.com'
+    )
+    expect(urlHelper.getServerApiUrl('https://GitHub.com')).toBe(
+      'https://api.github.com'
+    )
+    expect(urlHelper.getServerApiUrl('https://contoso.ghe.com')).toBe(
+      'https://api.contoso.ghe.com'
+    )
+    expect(urlHelper.getServerApiUrl('https://fabrikam.GHE.COM')).toBe(
+      'https://api.fabrikam.ghe.com'
+    )
+    expect(
+      urlHelper.getServerApiUrl('https://src.onpremise.fabrikam.com')
+    ).toBe('https://src.onpremise.fabrikam.com/api/v3')
+  })
+})

action.yml

@@ -9,6 +9,9 @@ inputs:
       The branch, tag or SHA to checkout. When checking out the repository that
       triggered a workflow, this defaults to the reference or SHA for that
       event.  Otherwise, uses the default branch.
+  default-branch-checkout:
+    description: 'Indicates whether to checkout the default repository branch if the requested ref does not exist'
+    default: false
   token:
     description: >
       Personal access token (PAT) used to fetch the repository. The PAT is configured

dist/index.js

@@ -1278,7 +1278,7 @@ function getSource(settings) {
             else if (settings.sparseCheckout) {
                 fetchOptions.filter = 'blob:none';
             }
-            if (settings.fetchDepth <= 0) {
+            if (settings.fetchDepth <= 0 || settings.defaultBranchCheckout) {
                 // Fetch all branches and tags
                 let refSpec = refHelper.getRefSpecForAllHistory(settings.ref, settings.commit);
                 yield git.fetch(refSpec, fetchOptions);
@@ -1298,7 +1298,22 @@ function getSource(settings) {
             core.endGroup();
             // Checkout info
             core.startGroup('Determining the checkout info');
-            const checkoutInfo = yield refHelper.getCheckoutInfo(git, settings.ref, settings.commit);
+            let checkoutInfo;
+            try {
+                checkoutInfo = yield refHelper.getCheckoutInfo(git, settings.ref, settings.commit);
+            }
+            catch (error) {
+                if (settings.defaultBranchCheckout) {
+                    core.info('Could not determine the checkout info. Trying the default repository branch');
+                    const repositoryDefaultBranch = settings.sshKey
+                        ? yield git.getDefaultBranch(repositoryUrl)
+                        : yield githubApiHelper.getDefaultBranch(settings.authToken, settings.repositoryOwner, settings.repositoryName);
+                    checkoutInfo = yield refHelper.getCheckoutInfo(git, repositoryDefaultBranch, settings.commit);
+                }
+                else {
+                    throw error;
+                }
+            }
             core.endGroup();
             // LFS fetch
             // Explicit lfs-fetch to avoid slow checkout (fetches one lfs object at a time).
@@ -1763,6 +1778,11 @@ function getInputs() {
         }
         core.debug(`ref = '${result.ref}'`);
         core.debug(`commit = '${result.commit}'`);
+        // Default branch checkout
+        result.defaultBranchCheckout =
+            (core.getInput('default-branch-checkout') || 'false').toUpperCase() ===
+                'TRUE';
+        core.debug(`default-branch-checkout = '${result.defaultBranchCheckout}'`);
         // Clean
         result.clean = (core.getInput('clean') || 'true').toUpperCase() === 'TRUE';
         core.debug(`clean = ${result.clean}`);
@@ -2005,8 +2025,8 @@ function getCheckoutInfo(git, ref, commit) {
             result.ref = ref;
         }
         // refs/
-        else if (upperRef.startsWith('REFS/') && commit) {
+        else if (upperRef.startsWith('REFS/')) {
-            result.ref = commit;
+            result.ref = commit ? commit : ref;
         }
         // Unqualified ref, check for a matching branch or tag
         else {
@@ -2454,22 +2474,50 @@ function getFetchUrl(settings) {
     return `${serviceUrl.origin}/${encodedOwner}/${encodedName}`;
 }
 function getServerUrl(url) {
-    let urlValue = url && url.trim().length > 0
+    let resolvedUrl = process.env['GITHUB_SERVER_URL'] || 'https://github.com';
-        ? url
+    if (hasContent(url, WhitespaceMode.Trim)) {
-        : process.env['GITHUB_SERVER_URL'] || 'https://github.com';
+        resolvedUrl = url;
-    return new url_1.URL(urlValue);
+    }
+    return new url_1.URL(resolvedUrl);
 }
 function getServerApiUrl(url) {
-    let apiUrl = 'https://api.github.com';
+    if (hasContent(url, WhitespaceMode.Trim)) {
-    if (isGhes(url)) {
+        let serverUrl = getServerUrl(url);
-        const serverUrl = getServerUrl(url);
+        if (isGhes(url)) {
-        apiUrl = new url_1.URL(`${serverUrl.origin}/api/v3`).toString();
+            serverUrl.pathname = 'api/v3';
+        }
+        else {
+            serverUrl.hostname = 'api.' + serverUrl.hostname;
+        }
+        return pruneSuffix(serverUrl.toString(), '/');
     }
-    return apiUrl;
+    return process.env['GITHUB_API_URL'] || 'https://api.github.com';
 }
 function isGhes(url) {
-    const ghUrl = getServerUrl(url);
+    const ghUrl = new url_1.URL(url || process.env['GITHUB_SERVER_URL'] || 'https://github.com');
-    return ghUrl.hostname.toUpperCase() !== 'GITHUB.COM';
+    const hostname = ghUrl.hostname.trimEnd().toUpperCase();
+    const isGitHubHost = hostname === 'GITHUB.COM';
+    const isGitHubEnterpriseCloudHost = hostname.endsWith('.GHE.COM');
+    const isLocalHost = hostname.endsWith('.LOCALHOST');
+    return !isGitHubHost && !isGitHubEnterpriseCloudHost && !isLocalHost;
+}
+function pruneSuffix(text, suffix) {
+    if (hasContent(suffix, WhitespaceMode.Preserve) && (text === null || text === void 0 ? void 0 : text.endsWith(suffix))) {
+        return text.substring(0, text.length - suffix.length);
+    }
+    return text;
+}
+var WhitespaceMode;
+(function (WhitespaceMode) {
+    WhitespaceMode[WhitespaceMode["Trim"] = 0] = "Trim";
+    WhitespaceMode[WhitespaceMode["Preserve"] = 1] = "Preserve";
+})(WhitespaceMode || (WhitespaceMode = {}));
+function hasContent(text, whitespaceMode) {
+    let refinedText = text !== null && text !== void 0 ? text : '';
+    if (whitespaceMode == WhitespaceMode.Trim) {
+        refinedText = refinedText.trim();
+    }
+    return refinedText.length > 0;
 }
 
 

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "checkout",
-  "version": "4.1.7",
+  "version": "4.2.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "checkout",
-      "version": "4.1.7",
+      "version": "4.2.2",
       "license": "MIT",
       "dependencies": {
         "@actions/core": "^1.10.1",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "checkout",
-  "version": "4.1.7",
+  "version": "4.2.2",
   "description": "checkout action",
   "main": "lib/main.js",
   "scripts": {

src/git-source-provider.ts

@@ -169,7 +169,7 @@ export async function getSource(settings: IGitSourceSettings): Promise<void> {
       fetchOptions.filter = 'blob:none'
     }
 
-    if (settings.fetchDepth <= 0) {
+    if (settings.fetchDepth <= 0 || settings.defaultBranchCheckout) {
       // Fetch all branches and tags
       let refSpec = refHelper.getRefSpecForAllHistory(
         settings.ref,
@@ -193,11 +193,34 @@ export async function getSource(settings: IGitSourceSettings): Promise<void> {
 
     // Checkout info
     core.startGroup('Determining the checkout info')
-    const checkoutInfo = await refHelper.getCheckoutInfo(
+    let checkoutInfo: refHelper.ICheckoutInfo
-      git,
+    try {
-      settings.ref,
+      checkoutInfo = await refHelper.getCheckoutInfo(
-      settings.commit
+        git,
-    )
+        settings.ref,
+        settings.commit
+      )
+    } catch (error) {
+      if (settings.defaultBranchCheckout) {
+        core.info(
+          'Could not determine the checkout info. Trying the default repository branch'
+        )
+        const repositoryDefaultBranch = settings.sshKey
+          ? await git.getDefaultBranch(repositoryUrl)
+          : await githubApiHelper.getDefaultBranch(
+              settings.authToken,
+              settings.repositoryOwner,
+              settings.repositoryName
+            )
+        checkoutInfo = await refHelper.getCheckoutInfo(
+          git,
+          repositoryDefaultBranch,
+          settings.commit
+        )
+      } else {
+        throw error
+      }
+    }
     core.endGroup()
 
     // LFS fetch

src/git-source-settings.ts

@@ -19,6 +19,11 @@ export interface IGitSourceSettings {
    */
   ref: string
 
+  /**
+   * Indicates whether to checkout the default repository branch if the requested ref does not exist
+   */
+  defaultBranchCheckout: boolean
+
   /**
    * The commit to checkout
    */

src/input-helper.ts

@@ -78,6 +78,12 @@ export async function getInputs(): Promise<IGitSourceSettings> {
   core.debug(`ref = '${result.ref}'`)
   core.debug(`commit = '${result.commit}'`)
 
+  // Default branch checkout
+  result.defaultBranchCheckout =
+    (core.getInput('default-branch-checkout') || 'false').toUpperCase() ===
+    'TRUE'
+  core.debug(`default-branch-checkout = '${result.defaultBranchCheckout}'`)
+
   // Clean
   result.clean = (core.getInput('clean') || 'true').toUpperCase() === 'TRUE'
   core.debug(`clean = ${result.clean}`)

src/ref-helper.ts

@@ -46,8 +46,8 @@ export async function getCheckoutInfo(
     result.ref = ref
   }
   // refs/
-  else if (upperRef.startsWith('REFS/') && commit) {
+  else if (upperRef.startsWith('REFS/')) {
-    result.ref = commit
+    result.ref = commit ? commit : ref
   }
   // Unqualified ref, check for a matching branch or tag
   else {

src/url-helper.ts

@@ -21,26 +21,61 @@ export function getFetchUrl(settings: IGitSourceSettings): string {
 }
 
 export function getServerUrl(url?: string): URL {
-  let urlValue =
+  let resolvedUrl = process.env['GITHUB_SERVER_URL'] || 'https://github.com'
-    url && url.trim().length > 0
+  if (hasContent(url, WhitespaceMode.Trim)) {
-      ? url
+    resolvedUrl = url!
-      : process.env['GITHUB_SERVER_URL'] || 'https://github.com'
+  }
-  return new URL(urlValue)
+
+  return new URL(resolvedUrl)
 }
 
 export function getServerApiUrl(url?: string): string {
-  let apiUrl = 'https://api.github.com'
+  if (hasContent(url, WhitespaceMode.Trim)) {
+    let serverUrl = getServerUrl(url)
+    if (isGhes(url)) {
+      serverUrl.pathname = 'api/v3'
+    } else {
+      serverUrl.hostname = 'api.' + serverUrl.hostname
+    }
 
-  if (isGhes(url)) {
+    return pruneSuffix(serverUrl.toString(), '/')
-    const serverUrl = getServerUrl(url)
-    apiUrl = new URL(`${serverUrl.origin}/api/v3`).toString()
   }
 
-  return apiUrl
+  return process.env['GITHUB_API_URL'] || 'https://api.github.com'
 }
 
 export function isGhes(url?: string): boolean {
-  const ghUrl = getServerUrl(url)
+  const ghUrl = new URL(
+    url || process.env['GITHUB_SERVER_URL'] || 'https://github.com'
+  )
 
-  return ghUrl.hostname.toUpperCase() !== 'GITHUB.COM'
+  const hostname = ghUrl.hostname.trimEnd().toUpperCase()
+  const isGitHubHost = hostname === 'GITHUB.COM'
+  const isGitHubEnterpriseCloudHost = hostname.endsWith('.GHE.COM')
+  const isLocalHost = hostname.endsWith('.LOCALHOST')
+
+  return !isGitHubHost && !isGitHubEnterpriseCloudHost && !isLocalHost
+}
+
+function pruneSuffix(text: string, suffix: string) {
+  if (hasContent(suffix, WhitespaceMode.Preserve) && text?.endsWith(suffix)) {
+    return text.substring(0, text.length - suffix.length)
+  }
+  return text
+}
+
+enum WhitespaceMode {
+  Trim,
+  Preserve
+}
+
+function hasContent(
+  text: string | undefined,
+  whitespaceMode: WhitespaceMode
+): boolean {
+  let refinedText = text ?? ''
+  if (whitespaceMode == WhitespaceMode.Trim) {
+    refinedText = refinedText.trim()
+  }
+  return refinedText.length > 0
 }