Lettuce Docs Tags Graph

lettuce deploy

#docs#cli#reference
~3 min read

lettuce deploy

Build the vault into a static site and push it to GitHub Pages in one step.

lettuce deploy [vault] [options]

deploy is a single flat command — there are no subcommands. It publishes the vault (the same build 03 lettuce publish performs) and then commits and pushes the result to a GitHub repository on a Pages branch.

The vault is a positional argument (the first non-dash argument); it defaults to the current directory if omitted.

Flags

Flag Default Purpose
--repo owner/repo — Target GitHub repository (e.g. DrBaher/notes).
--remote URL — Push to an explicit git remote URL instead of --repo.
--branch BRANCH gh-pages Branch to publish to.
--message MSG Publish from Lettuce Commit message.
--token TOKEN $GITHUB_TOKEN GitHub token. Falls back to the GITHUB_TOKEN environment variable.
--base-url URL — Public base URL written into the built site.
--contact EMAIL — Contact email embedded in the build.
--private off Create the repository as private. Repos are public by default.
--all off Publish all notes, not just those with published: true.

You must supply either --repo owner/repo or --remote URL. When using --repo, you also need a token via --token or $GITHUB_TOKEN.

Examples

Deploy a vault to a GitHub Pages repo (public):

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
lettuce deploy ~/Notes --repo DrBaher/notes

Deploy every note (including drafts) to a private repo with a custom message:

lettuce deploy ~/Notes --repo DrBaher/notes --private --all \
  --message "Nightly publish"

Set the public base URL and a contact email:

lettuce deploy ~/Notes --repo DrBaher/notes \
  --base-url https://drbaher.github.io/notes/ \
  --contact you@example.com

Push to an explicit remote URL instead of a owner/repo slug:

lettuce deploy ~/Notes --remote https://github.com/DrBaher/notes.git --token "$GITHUB_TOKEN"

Token

Use a fine-grained GitHub token with Contents: Read/Write on the target repository. Pass it with --token, or set it once in the environment as GITHUB_TOKEN and let deploy pick it up automatically.

Common errors

Error Cause
deploy: specify --repo owner/repo (or --remote URL) Neither --repo nor --remote was given.
deploy: --repo needs --token or $GITHUB_TOKEN A --repo slug was given but no token is available.

CI deployment

If you’d rather build and deploy from CI:

# .github/workflows/publish.yml
on: { push: { branches: [main] } }
jobs:
  publish:
    runs-on: macos-14
    steps:
      - uses: actions/checkout@v4
      - run: brew install lettuce  # (or curl -fsSL https://lettuce.drbaher.com/install.sh | sh)
      - run: lettuce deploy --repo DrBaher/notes
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}