diff --git a/commit/README.md b/commit/README.md
new file mode 100644
index 0000000..f63d201
--- /dev/null
+++ b/commit/README.md
@@ -0,0 +1,51 @@
+# `commit` Github Action
+
+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 }}`).
+
+## Usage
+
+```yaml
+steps:
+  - name: Checkout
+    uses: actions/checkout@v6
+
+  - name: Make changes and stage them
+    run: |
+      echo "hello" > greeting.txt
+      git add greeting.txt
+
+  - name: Commit through API
+    uses: apify/workflows/commit@v0.43.0
+    with:
+      commit-message: "chore: add greeting"
+      github-token: ${{ secrets.YOUR_GITHUB_TOKEN_WITH_WRITE_PERMISSION }}
+```
+
+### 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.
+- `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.
+
+### Example: commit to a new branch
+
+```yaml
+steps:
+  - name: Checkout
+    uses: actions/checkout@v
+
+  - name: Make changes and stage them
+    run: |
+      echo "hello" > greeting.txt
+      git add greeting.txt
+
+  - name: Commit to a new branch
+    uses: apify/workflows/commit@v0.43.0
+    with:
+      commit-message: "chore: add greeting"
+      github-token: ${{ secrets.YOUR_GITHUB_TOKEN_WITH_WRITE_PERMISSION }}
+      branch: chore/add-greeting
+      create-branch: 'true'
+```
diff --git a/commit/action.yml b/commit/action.yml
index e67cecf..80a1f51 100644
--- a/commit/action.yml
+++ b/commit/action.yml
@@ -1,26 +1,35 @@
 name: Commit
 description: Creates a commit from the staged files through the GitHub GraphQL API (automatically signed)
 inputs:
+  github-token:
+    description: 'Token to authenticate API calls'
+    required: true
   commit-message:
     required: true
     description: 'The commit message'
-  branch:
-    description: 'Target branch name'
-    required: true
   repository:
-    description: 'Format: <owner>/<repo>'
-    required: true
-  github-token:
-    description: 'Token to authenticate API calls'
-    required: true
+    description: 'Format: `<owner>/<repo>`. Defaults to the current repository (`github.repository`).'
+    required: false
+    default: ${{ github.repository }}
+  branch:
+    description: 'Target branch name. Defaults to the current branch (`github.head_ref` on pull requests, otherwise `github.ref_name`). Required when `create-branch` is `true`.'
+    required: false
+    default: ${{ github.head_ref || github.ref_name }}
   create-branch:
-    description: 'Create branch if it does not exist'
+    description: 'Create branch if it does not exist. When `true`, `branch` must be passed explicitly.'
     default: 'false'
     required: false
 
 runs:
   using: composite
   steps:
+    - name: Validate inputs
+      if: ${{ inputs.create-branch == 'true' && inputs.branch == (github.head_ref || github.ref_name) }}
+      shell: bash
+      run: |
+        echo "::error::When 'create-branch' is true, 'branch' must be passed explicitly (it cannot default to the current branch '${{ github.head_ref || github.ref_name }}')."
+        exit 1
+
     - name: Create and checkout target branch
       if: ${{ inputs.create-branch == 'true' }}
       # The `shell` field is for some reason required when