5 min read
Update customized QBCore resources safely
Never overwrite a customized resource with a fresh download. Treat an update as a specific transition from a recorded deployed state to a reviewed target state, including callers, configuration and database changes.
This guide uses qb-target as the concrete resource example. Its config.lua, registrations and dependencies must be reviewed together. The accompanying Git exercise is a synthetic training fixture, not a real upstream release history or a FiveM runtime test.
Conceptual diagram; verify the behavior against your installed resource version.
Inventory
For each resource, record upstream URL, deployed commit or release archive, local branch, uncommitted files, configuration owner, schema files and dependent resources. Pin the target before beginning; main can change during the review.
# Run inside the individual resource repository, not the server data root.
git remote -v
git status --short
git rev-parse HEAD
git log --oneline --decorate -10Stop when the working tree contains unexplained changes. Save reviewed customization in a local branch/commit and preserve untracked files separately. Do not commit credentials or backup dumps. A Git tag does not capture uncommitted files, and a code backup is not a database backup.
Compare without changing production
Work in a staging copy. Verify the actual default branch and remote instead of assuming every resource uses main. The example below assumes you have verified origin and its main branch:
git fetch origin main
git rev-parse HEAD
git rev-parse origin/main
git diff --stat HEAD..origin/main
git diff HEAD..origin/main -- fxmanifest.lua config.lua registration.lua client.luaRead the release notes and changed code before merging. For the documented qb-target baseline, inspect PolyZone, config.lua, registration.lua and data/ as well as callers. For inventory, review API and storage migration separately.
Worked update: retain a custom targeting distance
Assume the operator has deliberately customized Config.MaxDistance to 2.0, and an incoming change touches the same line. Those numbers are training values, not recommended defaults or claims about an upstream release.
Record a recoverable baseline
With a clean, reviewed staging working tree:
git tag docs-before-target-update
git switch -c docs/update-target
TARGET_COMMIT=$(git rev-parse origin/main)
printf 'Review target: %s\n' "$TARGET_COMMIT"
git merge --no-commit --no-ff "$TARGET_COMMIT"Use a unique tag/branch name if these already exist. The tag points to the customized deployed baseline, not merely the original vendor commit. Keep the target SHA in the update record. If Git reports a conflict, the merge stopping is expected; do not run unrelated restore/reset commands.
Resolve a config conflict deliberately
A representative conflict might look like this:
<<<<<<< HEAD
Config.MaxDistance = 2.0
=======
Config.MaxDistance = 5.0
>>>>>>> incoming-updateRead why the incoming value changed. If the local 2.0 remains compatible with the new implementation, resolve that line to 2.0 while retaining other reviewed incoming changes. Do not accept the entire file with --ours: that can silently discard new settings or fixes. Do not accept it wholesale with --theirs and lose your local requirements either.
git diff --name-only --diff-filter=U
# Edit each conflicted file, removing all conflict markers.
git add config.lua
git diff --cached --check
git diff --cached -- config.lua fxmanifest.lua registration.lua client.lua
git status --shortIf the change cannot be reconciled, git merge --abort returns to the clean pre-merge state. This is why recording a clean baseline matters. If it can, commit the reviewed merge on staging and record its resulting SHA; a successful merge is not permission to deploy it.
Run the reproducible Git exercise
From the documentation repository, run:
bash scripts/examples/resource-update-fixture.shThe script creates an isolated temporary Git repository, introduces a real same-line config conflict, verifies abort, resolves the conflict while retaining another incoming setting, and verifies a baseline rollback. It uses no network, no production directory and no player database. It prints stage results and removes only its own temporary directory.
This tests the Git mechanics described here. It does not prove that changing a targeting distance is correct for your server. The fixture is also exercised by the documentation regression tests.
Staging acceptance tests
For a qb-target update, keep a small known fixture: one BoxZone, one NPC interaction, an allowed/denied job condition and a server-authorized action. The target guide supplies the registration patterns.
| Check | Pass evidence | Rollback trigger |
|---|---|---|
| Startup | Required resources start; no new error before registration | Missing export, dependency or syntax error |
| Zone geometry | Known outline and action at measured position/height | Zone missing or interaction reach changed unexpectedly |
| Job/item restrictions | Allowed player sees option; denied player does not | Filter regression |
| Server authorization | Wrong job or remote request is rejected | Any unauthorized operation succeeds |
| Resource lifecycle | Registrations disappear/reappear as designed during coordinated restart | Duplicate or missing registrations |
| Integration | Existing menu/stash action and reconnect still work | Caller mismatch or persistent state regression |
These are manual FiveM acceptance checks. Record actual results, resource SHAs and tested scenarios; do not label them passed merely because a documentation build or Git fixture passed.
Rollout
Back up files and the database, prove restoration in staging, resolve the reviewed update, and run the acceptance matrix. Then schedule an approved maintenance window, pause relevant writes, deploy the exact reviewed commit set and perform the same smoke checks. Record the deployed SHAs and rollback triggers.
Do not hot-restart qb-core underneath players as a general update method. A standalone UI resource, an inventory migration and a coordinated core update have different lifecycle requirements. Use your existing compatibility checklist and backup guide.
Rollback
Before production deployment, prepare a rollback artifact from the known baseline rather than an emergency git reset --hard in a directory containing untracked customization:
# In the reviewed repository; code only, not assets outside Git or the database.
git archive --format=tar docs-before-target-update > ../qb-target-before-update.tarKeep that archive and required external assets in a private backup location. During recovery, stop the affected coordinated resource set, restore the previous artifact/configuration and restart through the established deployment process. Verify the restored SHA and smoke tests.
For a schema/data migration, restoring files is insufficient. Restore the matched database snapshot or execute a previously tested reverse migration. Decide how to reconcile legitimate transactions made after the backup; silently discarding those writes is not a safe rollback.
Sources
- qb-target pinned resource.
- Git merge documentation: conflicts,
--no-commit,--no-ffand abort behavior. - Git archive documentation: archive a named tree.
- Inventory migrations and update conflicts.
Found an issue in this guide?
Send the page URL, the affected example, and a source or reproduction to the site maintainer. For a server or resource problem, use the support guide.
