Merge pull request #47 from vince-winkintel/docs/multi-agent-gitlab-identities

docs: clarify multi-agent GitLab identity setup

SKILL.md

@@ -49,6 +49,20 @@ glab ci view                       # View pipeline status
 glab repo view --web              # Open repo in browser
 ```
 
+## Multi-agent identity note
+
+When you want different agents to appear as different GitLab users, give each agent its own GitLab bot/service account. Multiple personal access tokens on the same GitLab user still act as that same visible identity.
+
+A practical pattern is one env file per agent, for example `~/.config/openclaw/env/gitlab-reviewer.env` and `~/.config/openclaw/env/gitlab-release.env`. Keep these env files outside version control, restrict their permissions (for example `chmod 600`), be mindful of backup exposure, and use least-privilege bot/service-account tokens. If those files use plain `KEY=value` lines, load them with exported vars before running `glab`:
+
+```bash
+set -a
+source ~/.config/openclaw/env/gitlab-<agent>.env
+set +a
+```
+
+Plain `source` updates the current shell but may not export variables to child processes such as `glab`. If the token/host vars are not exported, `glab` may silently fall back to shared stored auth from `~/.config/glab-cli/config.yml`, which can make the wrong account appear to perform the action.
+
 ## Skill organization
 
 This skill routes to specialized sub-skills by GitLab domain:

glab-auth/SKILL.md

@@ -62,6 +62,37 @@ glab auth login \
 
 **CI auto-login (GA in v1.90.0):** when enabled, token environment variables such as `GITLAB_TOKEN`, `GITLAB_ACCESS_TOKEN`, or `OAUTH_TOKEN` still take precedence over stored credentials and `CI_JOB_TOKEN`.
 
+### Agentic and multi-account setups
+
+If you need different agents to show up as different GitLab users, use distinct GitLab bot/service accounts. Multiple PATs on one GitLab user are useful for rotation or scope separation, but they do **not** create distinct visible identities.
+
+A good operational pattern is one env file per agent:
+
+```bash
+# ~/.config/openclaw/env/gitlab-reviewer.env
+GITLAB_TOKEN=glpat-...
+GITLAB_HOST=gitlab.com
+```
+
+Keep these env files outside version control, restrict their permissions (for example `chmod 600`), be mindful of backup exposure, and prefer least-privilege bot/service-account tokens.
+
+If the file uses plain `KEY=value` lines, load it with exported vars before running `glab`:
+
+```bash
+set -a
+source ~/.config/openclaw/env/gitlab-<agent>.env
+set +a
+
+glab auth status --hostname "$GITLAB_HOST"
+```
+
+Why this matters:
+- plain `source` does not necessarily export variables to child processes
+- `glab` only sees env vars that are exported
+- if `glab` cannot see the env token, it may silently fall back to shared stored auth in `~/.config/glab-cli/config.yml`
+
+That fallback is convenient for humans, but in multi-agent automation it can cause the wrong GitLab account to post comments, create MRs, or approve work.
+
 ### Switching accounts/instances
 
 1. **Logout from current:**
@@ -76,7 +107,7 @@ glab auth login \
 
 3. **Verify:**
    ```bash
-   glab auth status
+   glab auth status --hostname gitlab.company.com
    ```
 
 ### Docker registry access

glab-config/SKILL.md

@@ -68,6 +68,30 @@ glab config get https_proxy --host gitlab.mycompany.com
 
 **Precedence:** Per-host config overrides global config. Global config overrides the `HTTPS_PROXY` / `https_proxy` environment variables.
 
+## Env-first agent pattern
+
+For agentic setups, prefer per-agent env files over one shared shell profile. Example:
+
+```bash
+# ~/.config/openclaw/env/gitlab-reviewer.env
+GITLAB_TOKEN=glpat-...
+GITLAB_HOST=gitlab.com
+```
+
+Keep these env files outside version control, restrict their permissions (for example `chmod 600`), be mindful of backup exposure, and use least-privilege bot/service-account tokens.
+
+Load plain `KEY=value` env files like this so the variables are exported to `glab`:
+
+```bash
+set -a
+source ~/.config/openclaw/env/gitlab-<agent>.env
+set +a
+```
+
+A plain `source ~/.config/openclaw/env/gitlab-<agent>.env` updates the current shell but may leave the values unexported. In that case `glab` can miss the env overrides and silently reuse stored auth from `~/.config/glab-cli/config.yml`.
+
+Use distinct GitLab bot/service accounts when agents need distinct visible identities. Multiple PATs on one GitLab user still act as that same user.
+
 ## Common Settings
 
 ```bash