Sourcetree Custom Actions: One‑Click Git Workflow Automation

Why Custom Actions Matter

When you’re juggling commits, branches, and pull requests inside Sourcetree, the GUI can feel like a bottleneck. Custom Actions let you bind a single menu click to any shell script or executable, passing contextual Git data so you can, for example, open a commit in GitHub, run a linter on changed files, or trigger CI pipelines—all from within the app.

How the Mechanism Works

Custom Actions are defined in Preferences > Custom Actions. Each entry contains:

• Menu Caption – the text shown in the context menu.
• Executable – the program or script to run.
• Parameters – a string that Sourcetree expands using variables before launching the executable.
• Options – whether to capture output, run silently, or show a progress dialog.

When you invoke an action, Sourcetree substitutes variables such as $SHA (selected commit hash), $FILE (selected file path), $BRANCH, or $REPO (repository root). The expanded command is then executed in a local shell environment.

Parameter Substitution Example

# Example parameters string
https://github.com/owner/repo/commit/$SHA

On macOS, you would pair this with the open command; on Windows, use cmd /c start.

Worked Configuration: “Open in GitHub”

1. Open Preferences → Custom Actions → Add.
2. Menu Caption: Open in GitHub.
3. Executable:
   • macOS: open
   • Windows: cmd
   • Linux: xdg-open
4. Parameters:
   • macOS/Linux: https://github.com/owner/repo/commit/$SHA
   • Windows: /c start https://github.com/owner/repo/commit/$SHA
5. Show output in dialog: unchecked (browser launch is silent).

Now, right‑click any commit in the history view, choose Open in GitHub, and the default browser jumps straight to that commit page.

Testing Your Action

Before relying on an action, confirm the exact parameters Sourcetree passes:

1. Create a harmless action that writes its arguments to a temp file.
2. Run it on a known commit.
3. Open the file and verify that variables like $SHA resolved correctly.

Example test action (macOS):

Menu Caption: Log Parameters
Executable: /bin/echo
Parameters: Commit: $SHA Branch: $BRANCH
Output: Log to file
Output file: /tmp/sourcetree_params.log

Check /tmp/sourcetree_params.log for the rendered string.

Common Pitfalls and Limits

• Quoting Issues: Paths with spaces break scripts unless you wrap variables in quotes or let the target script handle raw arguments.
• Multiple Selections: On some versions, $FILE may return a space‑separated list; scripts should split or process accordingly.
• Environment Differences: The shell launched by Sourcetree does not load your regular login profile (e.g., .bashrc), so PATH extensions or SSH agents may be missing. Reference full paths or explicitly set environment variables in your script.
• Synchronous Execution: Long‑running actions block the GUI. Offload heavy work to background processes or use the --background flag if your script supports it.
• Per‑User Storage: Custom Actions live in the user profile, not in the repository. Share the configuration file manually or document it for teammates.

When to Use Custom Actions

• One‑click deployment triggers that require repository context.
• Opening specific URLs (GitHub, Jira, CI dashboards) tied to commits or branches.
• Running linters or test suites on the current selection without leaving the GUI.
• Automating repetitive file operations (e.g., moving a patch file to a shared folder).

Custom Actions are a lightweight, GUI‑based way to embed automation directly into your Git workflow, saving time and reducing context switches.