Fetching a user's email address from a SpaceForge Python hook

Last updated: November 2, 2026

When a run is triggered in Spacelift, the TF_VAR_spacelift_run_trigger environment variable provides the username of the triggering user. However, retrieving the associated email address requires a bit more work, especially when users authenticate via GitHub.

What Spacelift exposes natively

Spacelift does not expose a user's email address directly within a SpaceForge hook. The TF_VAR_spacelift_run_trigger variable only provides the username.

You may be able to look up an email via the Spacelift API using the managedUsers query, but only if Spacelift has an email stored for that user — for example, if they were invited by email or synced via SCIM. Users who authenticate exclusively through GitHub typically will not have an email stored in Spacelift.

Fetching the email via the GitHub API

If your users authenticate through GitHub, you can query the GitHub API from within a SpaceForge Python hook using your own GitHub token. Keep in mind that GitHub only returns a user's email address if they have made it publicly visible on their GitHub profile. For users with private emails, you will need to look up the address through your identity provider (e.g., Okta, Entra ID) instead.

To pass your GitHub token securely into the hook, provide it as a sensitive plugin parameter rather than hardcoding it.

Testing the plugin locally

You can test your SpaceForge plugin locally before installing it in Spacelift:

  1. Install SpaceForge:

    pip install spaceforge

  2. Set the required environment variables:

    export TF_VAR_spacelift_run_trigger=<github-username>
export GITHUB_TOKEN=<your-token>

  3. Run the plugin locally:

    python -m spaceforge run before_plan --plugin-file plugin.py

Installing the plugin in Spacelift

Once you are satisfied with the plugin, generate the plugin.yaml and install it in Spacelift by running:

python -m spaceforge generate plugin.py

When GitHub emails are not available

If your users keep their GitHub emails private, the GitHub API will not return them. In this case, your identity provider (such as Okta or Microsoft Entra ID) is the more reliable source for email lookups, as it typically stores verified email addresses for all users regardless of their GitHub privacy settings.