`@flowwright/plugin-git`

Git operations as step helpers, plus one stage builder for the checkout that most pipelines start with.

npm install --save-dev @flowwright/plugin-git

API

Export	Kind	Signature
`checkoutStage`	stage builder	`(url, opts?: CheckoutStageOptions) => StageDefinition`
`checkout`	step helper	`(url, opts?: CheckoutOptions) => Promise<void>`
`gitClone`	step helper	`(url, dir?) => Promise<void>`
`gitCheckout`	step helper	`(ref) => Promise<void>`
`gitTag`	step helper	`(name, opts?: { message?, push? }) => Promise<void>`
`gitPush`	step helper	`(opts?: { remote?, ref?, tags? }) => Promise<void>`

CheckoutOptions: ref, dir (default "."), depth, submodules, fetchTags. CheckoutStageOptions adds id (default "checkout"), needs and credential.

Example

pipeline.ts
import { pipeline, stage, sh } from "@flowwright/core";
import { checkoutStage, gitTag } from "@flowwright/plugin-git";

export default pipeline({
  name: "acme-api",
  stages: [
    checkoutStage("git@github.com:acme/api.git", {
      ref: "main",
      depth: 1,
      credential: "deploy-key",
    }),
    stage("Build", {
      needs: ["checkout"],
      run: async () => {
        await sh(["npm", "ci"]);
        await sh(["npm", "run", "build"]);
      },
    }),
    stage("Tag", {
      needs: ["build"],
      run: async () => {
        await gitTag("v1.0.0", { message: "release", push: true });
      },
    }),
  ],
});

What it composes down to

checkoutStage(url, { ref, depth, credential }) is one stage named Checkout, id checkout:

  checkout
      $ git clone --depth 1 -- git@github.com:acme/api.git .
      $ git -C . checkout main

With credential, the stage declares { id, as: "sshPrivateKey", env: "GIT_SSH_KEY" } and every step carries GIT_SSH_COMMAND='ssh -i "$GIT_SSH_KEY" -o IdentitiesOnly=yes'. Hand-written, that's:

stage("Checkout", {
  id: "checkout",
  credentials: [{ id: "deploy-key", as: "sshPrivateKey", env: "GIT_SSH_KEY" }],
  run: async () => {
    const env = { GIT_SSH_COMMAND: 'ssh -i "$GIT_SSH_KEY" -o IdentitiesOnly=yes' };
    await sh(["git", "clone", "--depth", "1", "--", url, "."], { env });
    await sh(["git", "-C", ".", "checkout", "main"], { env });
  },
});

Step order for checkout(): clone, then fetch --tags if fetchTags, then checkout <ref> if ref.

Other helpers:

Call	Step
`gitClone(url, "repo")`	`git clone -- <url> repo`
`gitCheckout("v1")`	`git checkout v1`
`gitTag("v1", { message: "m" })`	`git tag -a -m m -- v1`
`gitTag("v1", { push: true })`	…then `git push origin refs/tags/v1`
`gitPush({ remote: "up", ref: "main", tags: true })`	`git push --tags up main`

Gotchas

depth with a bare commit SHA doesn't work. A shallow clone only fetches the tip, so checking out an arbitrary SHA afterwards fails. Use a branch or tag as the ref, or drop depth.

Credentials aren't resolved by a local flow run. Declaring them is what makes the pipeline portable to a server, where resolution happens. Locally, use your own SSH agent. See Credentials.

The stage name is always Checkout. Only the id is configurable, via id.

API​

Example​

What it composes down to​

Gotchas​

API

Example

What it composes down to

Gotchas