DOC_INDEX

THEME

DOCS/Functions/git

git

A first-class function for Git operations - clone, checkout, fetch, list tags/branches, commit info, and push - with built-in auth and structured outputs

func: git performs common Git operations as a first-class step: cloning, checking out a ref, fetching, listing tags/branches, reading commit info, and committing + pushing. It handles authentication (token or SSH) and returns structured outputs (result.commit_sha, result.tags, ...) instead of making you parse git stdout. It runs with the workflow's merged environment, so tokens from env: / dotenv: / secrets: are available.

For any operation not listed below, drop to func: shell and run git directly.

Operations

Operation	`do:` shortcut	Purpose
`clone`	`clone <url> [dest]`	Clone a repo (shallow + single-branch by default)
`checkout`	`checkout <ref> -d <repo_dir>`	Check out a branch/tag/commit
`fetch`	— (use `args`)	Fetch from a remote
`list_tags`	`list-tags <repo_dir>`	List tags (returns `result.tags`)
`list_branches`	`list-branches <repo_dir>`	List branches (returns `result.branches`)
`commit_info`	`commit-info <repo_dir>`	Read HEAD commit metadata
`push`	`push <repo_dir> <branch> -m <msg>`	Stage, commit, and push

Two equivalent forms — the do: shortcut (quick) or args: (full control):

# do: shortcut
- { name: get, func: git, do: "clone https://github.com/org/repo.git work/repo" }

# args: form (same thing, with options)
- name: get
  func: git
  args:
    operation: clone
    url: https://github.com/org/repo.git
    dest: work/repo
    branch: main
    depth: 1

Parameters by operation

Operation	Required	Optional
`clone`	`url`	`dest`, `branch`, `tag`, `depth` (default 1, shallow), `recursive`, `force`, `auth`
`checkout`	`repo_dir`, `ref`	`force`, `create_branch`
`fetch`	`repo_dir`	`remote`, `prune`
`list_tags`	`repo_dir`	`pattern`
`list_branches`	`repo_dir`	—
`commit_info`	`repo_dir`	—
`push`	`repo_dir`, `message`	`branch`, `files`, `create_branch`, `dry_run`, `allow_empty`, `author` (or `author_name` + `author_email`), `committer`, `auth`

Authentication

Pass auth: with a type discriminator. Use {{ secrets.X }} for the token so it's masked and kept out of the run history:

# Token (HTTPS)
auth:
  type: token
  token: "{{ secrets.GITHUB_TOKEN }}"
  username: x-access-token        # optional

# SSH key
auth:
  type: ssh
  key_path: ~/.ssh/id_ed25519

A GIT_USERNAME environment variable is used as the default username if auth omits one.

Return values

func: git populates result with structured fields (only the ones relevant to the operation are set):

Field	Operations	Description
`result.success`	all	`true` on success
`result.commit_sha`	clone, checkout, push	Resolved commit SHA
`result.ref` / `result.branch`	checkout, clone	Checked-out ref / branch
`result.dest` (`result.path`)	clone	Destination path
`result.tags`	list_tags	List of tags
`result.branches`	list_branches	List of branches
`result.pushed`, `result.files_changed`	push	Push result
`result.fetched`, `result.refs_fetched`	fetch	Fetch result
`result.output`	all	Human-readable description

Examples

Clone a private repo with a token

- name: clone
  func: git
  args:
    operation: clone
    url: https://github.com/org/private-repo.git
    dest: work/repo
    branch: main
    auth:
      type: token
      token: "{{ secrets.GITHUB_TOKEN }}"
  # result.commit_sha, result.dest

Check out a specific version (reproducible)

- name: checkout
  func: git
  do: "checkout v1.2.3 -d work/repo"
  # or: args: { operation: checkout, repo_dir: work/repo, ref: v1.2.3 }

- name: tags
  func: git
  args:
    operation: list_tags
    repo_dir: work/repo
    pattern: "v*"
  outputs:
    latest: "{{ last (sortAlpha steps.tags.result.tags) }}"

Read the current commit

- name: head
  func: git
  do: "commit-info work/repo"
  # result.commit_sha, result.output

GitOps: commit + push state

- name: track_deploy
  func: git
  args:
    operation: push
    repo_dir: state-repo
    branch: "state/{{ vars.env }}"
    message: "Deploy {{ vars.version }} to {{ vars.env }}"
    files: ["deployed/{{ vars.env }}.yml"]
    create_branch: true
    author_name: "OrchStep Bot"
    author_email: "bot@orchstep.dev"
    auth:
      type: token
      token: "{{ secrets.GITHUB_TOKEN }}"
  # result.pushed, result.files_changed, result.commit_sha

Fetch with prune

- name: sync
  func: git
  args:
    operation: fetch
    repo_dir: work/repo
    prune: true

Retry a clone on a flaky network

- name: clone
  func: git
  do: "clone https://github.com/org/repo.git work/repo"
  retry:
    max_attempts: 3
    interval: 2s
    backoff_rate: 1.5
    when: '!result.success'

Anything else → `func: shell`

func: git covers the common operations. For rebases, cherry-picks, submodule gymnastics, or any flag not exposed above, use the shell:

- name: rebase
  func: shell
  do: "cd work/repo && git rebase origin/main"

Best practices

Tokens via secrets: — auth.token: "{{ secrets.GITHUB_TOKEN }}" keeps the credential masked in logs and out of the context store. Never inline a token.
Pin versions — check out a tag/SHA (ref: v1.2.3) for reproducible runs.
Shallow by default — clone uses depth: 1 + single-branch; raise depth only when you need history.
Use the structured outputs — read result.commit_sha / result.tags rather than regex-parsing git output.

Run it

orchstep run

< http assert >

git