feat: Add more inputs and outputs to the commit action to make it more useful (#298)

fnesveda · web-flow · commit a1e86199fa50 · 2026-05-15T15:49:34.000+02:00
We've decided to add a few inputs and outputs to the shared `commit` action to enable easier usage of it.

The changes are:
- added `path` input specifying which files should be staged before the commit
- added `pull` input specifying whether to call `git pull` before the commit and with what parameters
- added `retries` input specifying how many retries to do in case of errors
- renamed `commit-message` input to `message`
- added `committed` output saying `true` / `false` whether the commit actually happened, or whether there were no changes
- changed `commit-sha` output to `commit_sha`, and it contains the short SHA
- added `commit_long_sha` output

They mirror the interface of `EndBug/add-and-commit` for an easier migration from that action.
diff --git a/commit/README.md b/commit/README.md
@@ -2,54 +2,86 @@
 
 This action creates a commit from the staged files through the GitHub GraphQL API, so the commit is automatically signed by GitHub. The author of the commit will be the identity associated with the provided token (typically `github-actions[bot]` when using `${{ secrets.GITHUB_TOKEN }}`).
 
+By default the action stages everything in the working tree (`git add .`) before committing. Pass the `add` input to scope the staging, or set it to an empty string if you want to control staging yourself before calling the action.
+
 ## Usage
 
 ```yaml
 steps:
   - name: Checkout
     uses: actions/checkout@v6
 
-  - name: Make changes and stage them
+  - name: Make changes
     run: |
       echo "hello" > greeting.txt
-      git add greeting.txt
 
   - name: Commit through API
-    uses: apify/workflows/commit@v0.43.0
+    uses: apify/workflows/commit@v0.45.0
     with:
-      commit-message: "chore: add greeting"
+      message: "chore: add greeting"
       github-token: ${{ secrets.YOUR_GITHUB_TOKEN_WITH_WRITE_PERMISSION }}
+      add: greeting.txt
 ```
 
 ### Inputs
 
 - `github-token` (required) — Token used to authenticate the GraphQL call. Must have `contents: write` permission on the target repository.
-- `commit-message` (required) — The commit message.
+- `message` (required) — The commit message.
 - `repository` (optional, default `${{ github.repository }}`) — Target repository in `<owner>/<repo>` format.
 - `branch` (optional, default `${{ github.head_ref || github.ref_name }}`) — Target branch name. On pull requests this resolves to the PR's source branch (`github.head_ref`); on other events it resolves to `github.ref_name`. Required when `create-branch` is `true`.
 - `create-branch` (optional, default `false`) — When `true`, the action pushes `HEAD` to `branch` as a new remote branch before committing. `branch` must be passed explicitly in this case.
+- `add` (optional, default `.`) — Paths passed to `git add` before committing. Defaults to `.` (everything). When set to an empty string, `git add` is skipped entirely.
+- `pull` (optional, default `''`) — When non-empty, run `git pull <pull>` before staging and committing (e.g. `--rebase --autostash`). The special value `true` runs a plain `git pull` with no arguments. Defaults to an empty string (no pull).
+- `retries` (optional, default `0`) — How many times to retry the commit if it fails because the branch was updated by another author in the meantime. Requires `pull` to be non-empty (otherwise the action would just re-attempt against the same stale HEAD).
 
 ### Outputs
 
-- `commit-sha` — The SHA of the created commit.
+- `commit_sha` — The short (7-character) SHA of the created commit, or the current commit SHA if no new commit was created.
+- `commit_long_sha` — The full 40-character SHA of the created commit, or the current commit SHA if no new commit was created.
+- `committed` — `'true'` when a commit was created, `'false'` when there were no changes to commit.
 
 ### Example: commit to a new branch
 
 ```yaml
 steps:
   - name: Checkout
-    uses: actions/checkout@v
+    uses: actions/checkout@v6
 
-  - name: Make changes and stage them
-    run: |
-      echo "hello" > greeting.txt
-      git add greeting.txt
+  - name: Make changes
+    run: echo "hello" > greeting.txt
 
   - name: Commit to a new branch
-    uses: apify/workflows/commit@v0.43.0
+    uses: apify/workflows/commit@v0.45.0
     with:
-      commit-message: "chore: add greeting"
+      message: "chore: add greeting"
       github-token: ${{ secrets.YOUR_GITHUB_TOKEN_WITH_WRITE_PERMISSION }}
       branch: chore/add-greeting
       create-branch: 'true'
+      add: greeting.txt
 ```
+
+### Example: pull before committing
+
+When another job may push to the same branch concurrently, use `pull` and `retries` to fetch the latest changes before committing.
+
+```yaml
+steps:
+  - name: Checkout
+    uses: actions/checkout@v6
+
+  - name: Make changes
+    run: echo "hello" > greeting.txt
+
+  # Someone else would push to the same branch at this point.
+
+  - name: Commit through API
+    uses: apify/workflows/commit@v0.45.0
+    with:
+      message: "chore: add greeting"
+      github-token: ${{ secrets.YOUR_GITHUB_TOKEN_WITH_WRITE_PERMISSION }}
+      add: greeting.txt
+      pull: --rebase --autostash
+      retries: 3
+```
+
+This will retry the commit up to 3 times if it fails due to the branch being updated by another author, waiting with exponential backoff between attempts. The `pull` input is required for retries to work, as the action needs to fetch the new HEAD between attempts to avoid retrying against the same stale commit.
diff --git a/commit/action.yml b/commit/action.yml
@@ -4,7 +4,7 @@ inputs:
   github-token:
     description: 'Token to authenticate API calls'
     required: true
-  commit-message:
+  message:
     required: true
     description: 'The commit message'
   repository:
@@ -19,11 +19,29 @@ inputs:
     description: 'Create branch if it does not exist. When `true`, `branch` must be passed explicitly.'
     default: 'false'
     required: false
+  add:
+    description: 'Paths to stage before committing, passed to `git add`. Defaults to `.` (everything). When set to an empty string, `git add` is not called.'
+    default: '.'
+    required: false
+  pull:
+    description: 'When non-empty, run `git pull <pull>` before staging and committing (e.g. `--rebase --autostash`). The special value `true` runs a plain `git pull` with no arguments. Defaults to an empty string (no pull).'
+    default: ''
+    required: false
+  retries:
+    description: 'How many times to retry the commit if it fails because the branch was updated by another author in the meantime. Requires `pull` to be non-empty (so the action can fetch the new HEAD between attempts). Defaults to `0` (no retries).'
+    default: '0'
+    required: false
 
 outputs:
-  commit-sha:
-    description: 'The SHA of the created commit.'
-    value: ${{ steps.commit.outputs.commit-sha }}
+  commit_sha:
+    description: 'The short (7-character) SHA of the created commit. Falls back to the current HEAD SHA when no commit was made.'
+    value: ${{ steps.commit.outputs.commit_sha }}
+  commit_long_sha:
+    description: 'The full 40-character SHA of the created commit. Falls back to the current HEAD SHA when no commit was made.'
+    value: ${{ steps.commit.outputs.commit_long_sha }}
+  committed:
+    description: '`true` when a commit was created, `false` when there were no staged changes to commit.'
+    value: ${{ steps.commit.outputs.committed }}
 
 runs:
   using: composite
@@ -49,19 +67,32 @@ runs:
       run: |
         git checkout "${{ inputs.branch }}"
 
-    - name: Get HEAD SHA
-      id: get-head-sha
+    - name: Pull latest changes
+      if: ${{ inputs.pull != '' }}
       shell: bash
-      run: echo "head_ref=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+      run: |
+        if [[ "${{ inputs.pull }}" == "true" ]]; then
+          git pull
+        else
+          git pull ${{ inputs.pull }}
+        fi
+
+    - name: Stage files
+      if: ${{ inputs.add != '' }}
+      shell: bash
+      run: |
+        git add ${{ inputs.add }}
 
     - name: Commit through API
       id: commit
       uses: actions/github-script@v8
       env:
-        COMMIT_MESSAGE: ${{ inputs.commit-message }}
+        COMMIT_MESSAGE: ${{ inputs.message }}
         REPO: ${{ inputs.repository }}
-        EXPECTED_HEAD_OID: ${{ steps.get-head-sha.outputs.head_ref }}
         BRANCH: ${{ inputs.branch }}
+        ADD: ${{ inputs.add }}
+        PULL: ${{ inputs.pull }}
+        RETRIES: ${{ inputs.retries }}
       with:
         github-token: ${{ inputs.github-token }}
         script: |
diff --git a/commit/index.mts b/commit/index.mts
@@ -49,14 +49,44 @@ export function checkSupportedFileModes(status: GitFileStatus) {
     }
 }
 
-export async function main({ github, env, core }: { github: Octokit, env: Record<string, string>, core: typeof Core }) {
-    const {
-        COMMIT_MESSAGE,
-        REPO,
-        EXPECTED_HEAD_OID,
-        BRANCH,
-    } = env;
+/**
+ * Produces the list of staged files for committing.
+ */
+export async function status(options: Omit<childProcess.ExecOptions, 'encoding'> = {}): Promise<GitFileStatus[]> {
+    const cmd = [
+        'git',
+        'diff-index',
+        '--cached',      // only from the staging area (added files)
+        '--no-renames',  // do not track file renames (copy/move) - we only need added / removed
+        'HEAD',
+    ];
+
+    const stagedFileStatuses = (await exec(cmd.join(' '), { encoding: 'utf8', ...options })).stdout.trim();
 
+    // see: man git-diff-index(1) - section RAW OUTPUT FORMAT
+    return stagedFileStatuses.split('\n')
+        .map((line) => {
+            const tabSplit = line.split('\t');
+            if (tabSplit.length !== 2) {
+                return null;
+            }
+
+            const [info, filePath] = tabSplit;
+            const [modeBefore, modeAfter, shaBefore, shaAfter, fileStatus] = info.split(' ');
+
+            return {
+                modeBefore: parseInt(modeBefore.slice(1), 8),
+                modeAfter: parseInt(modeAfter, 8),
+                shaBefore,
+                shaAfter,
+                fileStatus,
+                filePath,
+            };
+        })
+        .filter((it) => !!it);
+}
+
+async function collectFileChanges(): Promise<FileChanges> {
     const fileChanges: FileChanges = { additions: [], deletions: [] };
     const stagedFiles = await status();
 
@@ -83,17 +113,22 @@ export async function main({ github, env, core }: { github: Octokit, env: Record
         }
     }
 
-    // Only log file paths not the base64 encoded file contents.
-    const changedPaths = {
-        additions: fileChanges.additions.map(({ path }) => path),
-        deletions: fileChanges.deletions.map(({ path }) => path),
-    };
-    core.info(`committing file changes: "${JSON.stringify(changedPaths, null, 4)}"`);
+    return fileChanges;
+}
+
+const RETRY_BASE_DELAY_MS = 1000;
 
-    const commitMessageLines = COMMIT_MESSAGE.split('\n');
-    const messageTitle = commitMessageLines[0];
-    const messageBody = commitMessageLines.slice(1).join('\n').trim();
+type CreateCommitArgs = {
+    github: Octokit;
+    repo: string;
+    branch: string;
+    expectedHeadOid: string;
+    messageTitle: string;
+    messageBody: string;
+    fileChanges: FileChanges;
+};
 
+async function createCommit({ github, repo, branch, expectedHeadOid, messageTitle, messageBody, fileChanges }: CreateCommitArgs): Promise<string> {
     const response = await github.graphql(`\
         mutation Commit($input: CreateCommitOnBranchInput!) {
             createCommitOnBranch(input: $input) {
@@ -106,56 +141,91 @@ export async function main({ github, env, core }: { github: Octokit, env: Record
         input: {
             fileChanges,
             branch: {
-                branchName: BRANCH,
-                repositoryNameWithOwner: REPO,
+                branchName: branch,
+                repositoryNameWithOwner: repo,
             },
-            expectedHeadOid: EXPECTED_HEAD_OID,
+            expectedHeadOid,
             message: {
                 headline: messageTitle,
                 body: messageBody,
             },
         },
     }) as any;
 
-    const commitSha = response.createCommitOnBranch.commit.oid;
-    core.info(`successfully pushed commit "${commitSha}"`);
-
-    core.setOutput('commit-sha', commitSha);
+    return response.createCommitOnBranch.commit.oid;
 }
 
-/**
- * Produces the list of staged files for committing.
- */
-export async function status(options: Omit<childProcess.ExecOptions, 'encoding'> = {}): Promise<GitFileStatus[]> {
-    const cmd = [
-        'git',
-        'diff-index',
-        '--cached',      // only from the staging area (added files)
-        '--no-renames',  // do not track file renames (copy/move) - we only need added / removed
-        'HEAD',
-    ];
+export async function main({ github, env, core }: { github: Octokit, env: Record<string, string>, core: typeof Core }) {
+    const {
+        COMMIT_MESSAGE,
+        REPO,
+        BRANCH,
+        PULL = '',
+        RETRIES = '0',
+    } = env;
 
-    const stagedFileStatuses = (await exec(cmd.join(' '), { encoding: 'utf8', ...options })).stdout.trim();
+    const retries = parseInt(RETRIES, 10);
+    if (Number.isNaN(retries) || retries < 0) {
+        throw new Error(`'retries' must be a non-negative integer, got "${RETRIES}"`);
+    }
+    if (retries > 0 && PULL === '') {
+        throw new Error(`'retries' is set to ${retries} but 'pull' is empty — retrying requires 'pull' to be set so the action can fetch the new HEAD between attempts.`);
+    }
 
-    // see: man git-diff-index(1) - section RAW OUTPUT FORMAT
-    return stagedFileStatuses.split('\n')
-        .map((line) => {
-            const tabSplit = line.split('\t');
-            if (tabSplit.length !== 2) {
-                return null;
-            }
+    const commitMessageLines = COMMIT_MESSAGE.split('\n');
+    const messageTitle = commitMessageLines[0];
+    const messageBody = commitMessageLines.slice(1).join('\n').trim();
 
-            const [info, filePath] = tabSplit;
-            const [modeBefore, modeAfter, shaBefore, shaAfter, fileStatus] = info.split(' ');
+    const maxAttempts = retries + 1;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        if (PULL !== '') {
+            const pullCmd = PULL === 'true' ? 'git pull' : `git pull ${PULL}`;
+            core.info(`Executing "${pullCmd}" before committing (attempt ${attempt}/${maxAttempts})`);
+            await exec(pullCmd, { encoding: 'utf8' });
+        }
 
-            return {
-                modeBefore: parseInt(modeBefore.slice(1), 8),
-                modeAfter: parseInt(modeAfter, 8),
-                shaBefore,
-                shaAfter,
-                fileStatus,
-                filePath,
-            };
-        })
-        .filter((it) => !!it);
+        const expectedHeadOid = (await exec('git rev-parse HEAD', { encoding: 'utf8' })).stdout.trim();
+        const fileChanges = await collectFileChanges();
+
+        // Only log file paths not the base64 encoded file contents.
+        const changedPaths = {
+            additions: fileChanges.additions.map(({ path }) => path),
+            deletions: fileChanges.deletions.map(({ path }) => path),
+        };
+        core.info(`committing file changes: "${JSON.stringify(changedPaths, null, 4)}"`);
+
+        if (fileChanges.additions.length === 0 && fileChanges.deletions.length === 0) {
+            core.info('no staged changes — skipping commit');
+            core.setOutput('committed', 'false');
+            core.setOutput('commit_sha', expectedHeadOid.slice(0, 7));
+            core.setOutput('commit_long_sha', expectedHeadOid);
+            return;
+        }
+
+        try {
+            const commitSha = await createCommit({
+                github,
+                repo: REPO,
+                branch: BRANCH,
+                expectedHeadOid,
+                messageTitle,
+                messageBody,
+                fileChanges,
+            });
+            core.info(`successfully pushed commit "${commitSha}"`);
+
+            core.setOutput('commit_sha', commitSha.slice(0, 7));
+            core.setOutput('commit_long_sha', commitSha);
+            core.setOutput('committed', 'true');
+            return;
+        } catch (err) {
+            if (attempt < maxAttempts) {
+                const delayMs = RETRY_BASE_DELAY_MS * (2 ** (attempt - 1));
+                core.warning(`commit attempt ${attempt}/${maxAttempts} failed: ${err instanceof Error ? err.message : String(err)} — retrying in ${delayMs}ms`);
+                await new Promise((resolve) => { setTimeout(resolve, delayMs); });
+                continue;
+            }
+            throw err;
+        }
+    }
 }
diff --git a/commit/index.test.mts b/commit/index.test.mts
