gitstalk
Install the plugin Sign up
Docs: Environment variables

Environment variables live

Where you set one depends on what it is for. Pick the row that matches, then read what a run sees.

Where do I set it?

You need Use Read as
A credential (token, key, password) A secret, in Settings ${{ secrets.NAME }}
Plain configuration the whole team may read A variable, in Settings ${{ vars.NAME }}
A value for one workflow, job or step env: in the workflow YAML The environment, and ${{ env.NAME }}
Tests during a pre-land check env in .gitstalk/checks.yml The test process environment
Git inside a container or CI A deploy token and its Env vars block GITSTALK_TOKEN
To change Gitstalk's own behaviour for jobs A GITSTALK_* variable See Gitstalk's switches
To change how the setup script behaves A GITSTALK_* variable in your shell See The setup script

In a workflow

.github/workflows/ci.yml
env:
  LOG_LEVEL: info                       # every job
jobs:
  test:
    runs-on: ubuntu-latest
    env:
      TZ: UTC                           # this job
    steps:
      - run: npm test
        env:
          API_URL: ${{ vars.API_URL }}  # this step, from a variable
          API_KEY: ${{ secrets.API_KEY }}

A workflow's own env: wins over the defaults Gitstalk sets, such as NPM_CONFIG_AUDIT.

In a pre-land check

Pre-land checks run your tests on the merged tree. Their environment comes from the env map:

.gitstalk/checks.yml
env:
  TZ: UTC
  FEATURE_FLAGS: billing-v2
  • Names are upper case: letters, digits and underscores, starting with a letter or underscore.
  • At most 32 variables. Each value is at most 4000 characters.
  • The runner owns PATH, HOME and CI, and the prefixes GIT_, LD_, NODE_TEST and BWRAP. A file that sets one of them is a red check that says so.
  • The file is plain text in git, so never put a credential in it.

Git in a container or CI

A deploy token opens one repository, read or read and write, and expires. The repository's start page has a Connect git step with an Env vars tab, and Settings has Deploy tokens. Both show the block below, filled in for your repository.

Token nameAccess: read and write. Expires after 90 days.
CI
Create deploy token 
Credential helper
export GITSTALK_TOKEN=<deploy token>
export GIT_TERMINAL_PROMPT=0
export GIT_CONFIG_COUNT=1
export GIT_CONFIG_KEY_0='credential.https://gitstalk.dev.helper'
export GIT_CONFIG_VALUE_0='!f() { echo "username=x"; echo "password=$GITSTALK_TOKEN"; }; f'
The token is shown once. Store it as a CI secret, not in the repository. The block also comes as a Bearer header form.
  • git reads the token from GITSTALK_TOKEN and never prompts. It needs git 2.31 or newer, because the block uses GIT_CONFIG_*.
  • The credential only applies to the Gitstalk host, so other remotes keep their own credentials.
  • The expiry choices are 7 days, 30 days, 90 days and 1 year. Maintainers and the owner can manage deploy tokens in Settings. The start page tab offers creating one to the owner.

Gitstalk's switches

These are repository or org variables. Most have a form in Settings under Actions.

Variable Effect
GITSTALK_DEPS_CACHE off turns the dependency cache off.
GITSTALK_DEPS_SNAPSHOT_MAX Largest snapshot, such as 2GiB.
GITSTALK_NPM_AUDIT on (or true) keeps npm's audit inside installs. It is off by default.

The old BEANSTALK_* names are still read when the GITSTALK_* one is absent.

The setup script

The /setup.sh script connects git on your machine to your account. Set these in your shell before running it:

Variable Effect
GITSTALK_WEB The Gitstalk web app to talk to. The default is the public deployment. A self-hoster sets this.
GITSTALK_NO_BROWSER=1 Never open a browser. The script shows a code to enter on another device.
GITSTALK_CREDENTIAL_HELPER The git credential helper to use for the Gitstalk host. By default it uses the one git already uses, else the OS store, else store.

What a run sees

Actions jobs

  • The usual GITHUB_* variables, so scripts written for GitHub keep working. GITHUB_REF for a stalk run is refs/heads/main, and GITHUB_SERVER_URL is the Gitstalk web host.
  • CI=true.
  • GITSTALK_LINE=stalk and GITSTALK_REPOSITORY_ID, each also as BEANSTALK_*.
  • NPM_CONFIG_AUDIT=false and NPM_CONFIG_FUND=false, unless GITSTALK_NPM_AUDIT is on or true.
  • ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN for a job with id-token: write.

Automation runs

Variable Holds
GITSTALK_EVENT The name of the event, such as bean_red. The payload is a JSON file at $GITHUB_EVENT_PATH.
GITSTALK_AUTOMATION, GITSTALK_ACTOR The automation's id and the identity it acts as, <name>[automation].
GITSTALK_MEMORY_REF, GITSTALK_MEMORY The memory ref (empty when memory is off) and the directory the memory is restored into.
GITSTALK_WORK, GITSTALK_BEANS_FILE The scratch directory and a file listing the beans the run pushed.
GITSTALK_MODEL, GITSTALK_MAX_TURNS For the Prompt harness only: the model and the turn limit.
Each secret the file names As an environment variable of that name, in the agent or script step.

GITSTALK_EVENT, GITSTALK_AUTOMATION, GITSTALK_ACTOR, GITSTALK_MEMORY_REF and GITSTALK_MEMORY are also set as BEANSTALK_*, so older scripts keep working. GITSTALK_WORK, GITSTALK_BEANS_FILE, GITSTALK_MODEL and GITSTALK_MAX_TURNS are not. The container never holds a model key.

Running Gitstalk yourself

The deployment has its own settings, such as ACTIONS_MONTHLY_MINUTES. They are not environment variables of your jobs. See Limits and plans and Self-hosting.

Sources