Add naming option config

[Stevedow99]

Video Walkthrough

PR explanation video

• I walk through the WHY and WHAT in this video

Summary

Add a new optional ui_job_name_override field to job definitions that allows users to control the exact job name displayed in the dbt Cloud UI without the [[identifier]] suffix.

By default, dbt-jobs-as-code appends [[identifier]] to every job name for tracking purposes (e.g. Daily Job [[daily_job_prod]]). This is functional but clutters the UI. When ui_job_name_override is set, the tool sends that exact name to dbt Cloud instead, and uses name + project + environment matching to track the job on subsequent syncs.

Checklist

• Tests pass locally (uv run pytest)
• Code follows project style guidelines (ruff linting passes)
• New functionality includes appropriate tests
• Documentation has been updated if needed
• If this PR changes YAML fields: Run uv run dbt-jobs-as-code update-json-schema and commit the updated JSON schema

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update

Testing

Manual testing against live dbt Cloud (account 77338, project 136022)

1. Created a job with ui_job_name_override — verified it appears in dbt Cloud as the exact override name (no [[identifier]] suffix)
2. Ran plan after creation — verified the tool matches the override job by name and reports it as identical
3. Changed the ui_job_name_override value — verified plan detects the rename as an UPDATE (not a duplicate CREATE) and sync applies it
4. Ran plan after rename — verified the tool matches the job by its new override name and reports identical
5. Verified jobs without ui_job_name_override — confirmed existing behavior is completely unchanged (still uses [[identifier]] suffix)

What changed

File	Change
schemas/job.py	Added ui_job_name_override optional field. Updated to_payload() to use override name when set. Excluded from to_load_format() export.
schemas/__init__.py	Excluded ui_job_name_override from diff comparison; substitutes effective name for name when comparing so renames are detected.
schemas/load_job_schema.json	Added ui_job_name_override property to the JSON schema.
cloud_yaml_mapping/change_set.py	Added name-based matching for override jobs against untracked cloud jobs. Falls back to base name to handle renames.
docs/advanced_config/override_job_name.md	New documentation page.
docs/advanced_config/index.md	Added link to new doc page.

YAML usage

jobs:
  my_job:
    name: My Job
    ui_job_name_override: My Job
    # ... rest of config

When ui_job_name_override is absent or null, behavior is identical to before — fully backwards compatible.

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
src/dbt_jobs_as_code
main.py	310	160	48%	120–123, 129, 168–169, 200–203, 209, 245–329, 400–405, 418–419, 437–438, 442–444, 461–510, 539–597, 628–673, 678–679, 683
src/dbt_jobs_as_code/client
__init__.py	179	60	66%	16, 53–54, 62, 89–104, 119–120, 139–140, 147–157, 170–171, 187–188, 205, 215, 245–253, 295–310, 333, 349–350, 360–372, 375–386, 391–400
src/dbt_jobs_as_code/cloud_yaml_mapping
change_set.py	251	43	83%	27–29, 59, 65–66, 155, 212, 224, 247, 251–252, 258–260, 275–278, 299–318, 361–375, 428–450, 486–500
src/dbt_jobs_as_code/importer
__init__.py	27	7	74%	14–15, 22–27
src/dbt_jobs_as_code/schemas
__init__.py	25	3	88%	30, 72, 82
common_types.py	60	9	85%	7–8, 12–13, 29–30, 67–68, 91
config.py	14	3	79%	18, 24–25
job.py	120	7	94%	189, 222, 227, 233–242
TOTAL	1188	292	75%

Tests	Skipped	Failures	Errors	Time
123	0 💤	0 ❌	0 🔥	11.659s ⏱️

[Stevedow99]

@b-per Feel free to hit me up with slack on questions or edits that I need to make, thanks!

[b-per]

Hey! It will take some very hard convincing to implement this, and I am not convinced yet 😄

[[identifier]] is not added to job names without a reason. This is the way we can store state in the dbt platform.

Without this, we lose a lot of the functionality of the tool.
If jobs get renamed in the platform or in YAML we will lose the ability to know what they are referring to, leading to duplicate jobs all over the place etc...

---

I am not sure I am getting what is the show stopper of having [[ ]] in job names (knowing that it provides the ability to use this tool), but what we could do is try to find an alternative place for storing "the sate" that is not in the job name.

Ideally, we would have a field (hidden or not) in the platform API to store the jobs-as-code identifier for jobs. This would be the best and the cleanest but it has dependencies on modifying the code of the dbt platform to support that which we'd have to prioritize internally.

The other option I can think of would be to store this state in the job Description as an alternative to the job Name. It would still show in the platform UI if this is a show stopper for the customer but at least it won't be in the name itself.