Connect Google Jules to YazSes¶

Last checked against official Google Jules and GitHub documentation: 2026-09-23.

There are two different ways to use Jules with YazSes. Choose the one that matches who you are:

The recommended contribution architecture today is:

YazSes task
   ↓
your fork
   ↓
your Jules account
   ↓
you review the complete diff
   ↓
tests / task validation
   ↓
normal pull request to MSKazemi/yazses
   ↓
CI + human project review

This requires no upstream collaborator access.

Path A — contributor: connect Jules to your own fork¶

This is the normal and currently approved Jules workflow.

Step 1 — fork YazSes¶

1. Open the YazSes repository on GitHub.
2. Click Fork.
3. Create the fork under your own GitHub account.
4. Keep the repository name yazses unless you have a reason to change it.

Expected result: you have a repository such as:

YOUR_GITHUB_USERNAME/yazses

You do not need write permission to MSKazemi/yazses.

Step 2 — sign in to Jules¶

1. Open jules.google.com.
2. Sign in with the Google account you want to use for Jules.
3. Accept the Jules privacy notice if shown.
4. Click Connect to GitHub account.

Google's current setup flow redirects you to GitHub so you can authorize the connection and choose which repositories the Google Labs Jules GitHub App may access.

Step 3 — give Jules access to your fork only¶

On the GitHub installation/authorization screen:

1. Choose your own GitHub account.
2. Choose Only select repositories.
3. Select your fork, for example YOUR_GITHUB_USERNAME/yazses.
4. Review the permissions GitHub displays.
5. Click Install, Save, or the equivalent approval button shown by GitHub.
6. Return to Jules.

Expected result: your fork appears in the Jules repository/codebase selector.

Step 4 — set commit authoring correctly¶

For YazSes, use human-only Git authorship.

In Jules:

1. Open Settings.
2. Open Commit Authoring.
3. Select User only.

Expected result: future Jules commits use your identity as the commit author rather than making Jules the author/co-author.

YazSes allows tool disclosure in the pull request's AI assistance section, but automated tools are not project authors or co-authors. See root AGENTS.md.

Step 5 — configure the YazSes environment¶

In Jules:

1. Open your yazses codebase from the left sidebar/repository list.
2. Open Configuration.
3. In Initial Setup, enter:

uv sync

1. Click Run and Snapshot.

Jules currently documents an Ubuntu VM with Python, uv, pytest, ruff, mypy, Git, C/C++ compilers and other common developer tooling preinstalled. The uv sync step installs YazSes's repository dependencies.

Expected result: setup succeeds and Jules stores an environment snapshot for later tasks.

For the first setup only, you may use this slightly more verbose check:

uv --version
python --version
uv sync
uv run python -m pytest tests/test_agent_instructions.py -q

After it works, uv sync is sufficient as the normal initial setup.

Step 6 — verify Jules reads the YazSes rules¶

Before asking Jules to edit code, run one planning-only prompt:

Read AGENTS.md in this repository. Do not change any files.

Summarize:
1. the required setup/test commands;
2. the offline/network rule;
3. the rule for new feature defaults;
4. dependency/lazy-load rules;
5. authorship rules;
6. what evidence a cloud agent may not claim.

Do not create a branch or PR from this verification task.

A healthy result should identify at least:

• uv sync;
• pytest and ruff validation;
• no new runtime telemetry/network/cloud fallback without the repository's egress process;
• new features off by default;
• optional/lazy heavy dependencies;
• the human remains the responsible contributor;
• hardware, native-language and participant evidence cannot be invented by a cloud VM.

If it does not, stop and fix the repository selection/setup before asking Jules to implement work.

Step 7 — choose an eligible task¶

For campaign work, use:

uv run python scripts/check-task.py

Choose only a task that is:

• open;
• cloud_agent_ready: true;
• within the risk/worker rules in campaign/agent-workers.md;
• fully verifiable in a cloud/container environment.

Do not turn a hardware, native-language, accessibility-comfort, participant-research or other human-evidence task into a cloud task just because Jules says it can write the code.

Claim the task using the normal campaign claim workflow before starting.

Step 8 — give Jules the exact task contract¶

Use the campaign task/structured issue as the contract and tell Jules to read AGENTS.md.

A safe starting prompt is:

I am completing one YazSes contribution and remain responsible for the pull request.

Read AGENTS.md completely, then read TASK-ID and restate:
- the goal;
- allowed paths;
- explicit non-goals;
- acceptance/evidence requirements;
- validation command.

Inspect the implementation and tests before editing.
Make the smallest change that satisfies the task.
Stop if completion requires hardware evidence, native-language judgement,
participant/private data, credentials, billing changes, or a maintainer-only decision.

Run the task validation and relevant repository checks.
Show me the complete diff before I submit anything upstream.

Step 9 — review and validate before opening the PR¶

Do not treat "Jules finished" as "the contribution is finished."

Review every changed file, then run the task's exact validation. For ordinary Python changes, the project-wide gates are:

uv run python -m pytest tests/ -v
uv run ruff check src tests scripts
uv run mypy src

The task's narrower command should normally run first.

Step 10 — open a normal fork → upstream pull request¶

Push/create the branch in your fork, then open a pull request to:

base: MSKazemi/yazses : main
head: YOUR_GITHUB_USERNAME/yazses : your-branch

Complete the normal YazSes PR template, including:

• what changed;
• the related task/issue;
• commands you ran;
• AI assistance/tool disclosure if applicable;
• what you personally verified.

The PR goes through exactly the same CI and human review as any other contribution.

Contributor connection checklist¶

Before starting real work, all of these should be true:

• I have my own fork of YazSes.
• Jules is connected to my GitHub account.
• Google Labs Jules has access to my fork, not upstream.
• My fork appears in the Jules repository selector.
• Commit Authoring is User only.
• uv sync succeeds in Run and Snapshot.
• Jules correctly summarizes root AGENTS.md.
• My selected task is actually cloud-agent-ready.
• I understand that my provider account/quota/charges are my responsibility.
• I will review the complete diff before opening the PR.

If all ten are true, you are ready to use Jules for a fork-first YazSes contribution.

Path B — repository owner: direct upstream Jules connection¶

This is the future maintainer-controlled route where Jules can act directly from an upstream GitHub issue.

It is intentionally not enabled yet.

The live gate is #447 — JULES-SETUP-001.

Before upstream access is granted, #447 currently requires the relevant ADR/pilot/contract, read-only preflight, CI/ruleset and repository-protection gates to be complete. Read the issue itself for the authoritative current blocker list.

When #447 says the upstream gate is open¶

Only then should the repository owner perform these steps:

1. Open jules.google.com and sign in.
2. Click Connect to GitHub account.
3. On GitHub choose personal account MSKazemi.
4. Choose Only select repositories.
5. Select MSKazemi/yazses.
6. Review the GitHub App permissions carefully.
7. Install/save the GitHub App access.
8. Return to Jules and confirm MSKazemi/yazses appears in the repository selector.
9. Jules Settings → Commit Authoring → User only.
10. Open the YazSes codebase → Configuration.
11. Set Initial Setup to uv sync.
12. Click Run and Snapshot.
13. Run the planning-only AGENTS.md verification described above.
14. Verify the project's read-only Jules preflight passes for the chosen smoke issue.
15. Only then apply the literal jules GitHub issue label.

What the jules label means¶

Google currently documents the issue integration as:

open GitHub issue
    ↓
add label: jules
    ↓
Jules starts a task
    ↓
Jules comments on the issue
    ↓
finished task links to a PR for review

The label is case-insensitive in Jules, but YazSes treats the canonical spelling jules as an execution trigger.

It is not:

• a generic "AI friendly" tag;
• equivalent to agent-ready;
• permission to skip blockers;
• permission to merge automatically.

Selecting the first upstream smoke issue¶

Do not use #448 as the smoke task. #448 is the eligibility checker that must exist before the central smoke run.

The smoke issue must pass the current #447 requirements and the read-only pre-trigger checker. In the initial central deployment it should be small, cloud-completable, trusted/maintainer-approved, non-sensitive, and independent of hardware/native-language/research evidence.

Expected upstream result¶

After the owner deliberately adds jules to an eligible issue:

1. Jules should comment/start the task.
2. Jules should operate from the intended issue contract.
3. The resulting commit should use User only authorship.
4. Jules should produce/update a PR branch rather than bypass main.
5. Normal repository CI should run.
6. Human review remains mandatory before merge.

If any of those properties fail, stop the central rollout and use the emergency-disable procedure in

447.¶

Do contributors need access to the upstream repository?¶

No.

For normal community development:

contributor
    owns their fork
        ↓
Jules gets access to that fork
        ↓
contributor opens normal PR upstream

Do not make someone an upstream collaborator merely because they want to use Jules.

For MSKazemi/yazses, which is currently a personal-account repository, the owner controls the GitHub App installation used for direct upstream Jules access.

If the repository moves to a GitHub organization in the future, organization policy may add an owner/admin approval step for GitHub App installation.

If the repository is missing in Jules¶

For a repository you own/control:

GitHub profile photo → Settings → Applications → Google Labs Jules → Configure → Repository access

Then:

1. choose Only select repositories if appropriate;
2. add the intended repository;
3. save;
4. return to Jules;
5. refresh the repository selector.

Jules also currently exposes + Add repository at the bottom of its repository selector, which opens the GitHub repository-access flow.

If the jules issue label does nothing¶

For the upstream flow, check in this order:

1. The central-upstream gate in #447 is actually complete.
2. Google Labs Jules is installed for the account that owns MSKazemi/yazses.
3. The GitHub App has explicit access to MSKazemi/yazses.
4. The repository is visible in Jules.
5. The issue is in that repository and is open.
6. The label is exactly jules (case-insensitive according to Jules).
7. The project's own pre-trigger checker passed before the label was applied.

If the provider still does not react, use the provider's current support/feedback path rather than widening GitHub permissions.

If commits are attributed to Jules¶

Open:

Jules → Settings → Commit Authoring → User only

That setting applies to future Jules sessions. Correct the configuration before creating more YazSes work.

Do not add generated Co-Authored-By trailers. The PR may disclose Jules assistance and state what the human contributor verified; that is review disclosure, not authorship.

Removing or reducing Jules access¶

You can revoke access without changing YazSes code.

Remove one repository¶

On GitHub:

Profile photo → Settings → Applications → Google Labs Jules → Configure → Repository access

Remove the repository and save.

Remove the GitHub App entirely¶

From the same installed-app configuration area, use GitHub's suspend/uninstall/remove option if you no longer want the app to access resources owned by that account.

GitHub recommends periodically reviewing installed GitHub Apps and removing access that is no longer required.

Jules API key¶

The normal GitHub App + fork/issue workflow does not require a JULES_API_KEY.

If you separately create a Jules REST API key later, keep it outside the repository. Revoke it in Jules Settings when no longer needed.

Billing, credentials and private data¶

Before using Jules, read:

• Using AI coding agents safely
• Third-party AI tools

In particular:

• Jules is optional for contribution.
• Use your own provider account/quota for the fork-first workflow.
• YazSes does not authorize or reimburse third-party charges unless explicitly agreed in writing beforehand.
• Do not put provider/API/GitHub secrets in prompts, issues, source files or logs.
• Do not send user audio/transcripts, private repository material, research-participant data or non-deidentified tester data to a cloud coding agent.
• A task being agent-ready or cloud_agent_ready is not authority to spend money.

Official documentation¶

The provider UI can change; the current provider documentation takes precedence over button names in this page.

• Jules — Getting started
• Jules — Managing tasks and repositories
• Jules — Environment setup
• Jules — Running tasks
• Jules — issue-label integration
• Jules — commit authoring
• GitHub — installing a GitHub App from a third party
• GitHub — reviewing/modifying installed GitHub Apps

Related YazSes policy¶

• ADR-024 — distributed coding-agent worker model
• Cloud coding-agent workers
• Using AI coding agents safely
• Third-party AI tools
• #451 — coding-agent worker epic
• #447 — gated direct-upstream Jules setup