QBCore Frameworkqbcore.netCommunity docs
On this page

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.

QBCore staging rollout and rollback checklist

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 -10

Stop 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.lua

Read 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-update

Read 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 --short

If 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.sh

The 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.

CheckPass evidenceRollback trigger
StartupRequired resources start; no new error before registrationMissing export, dependency or syntax error
Zone geometryKnown outline and action at measured position/heightZone missing or interaction reach changed unexpectedly
Job/item restrictionsAllowed player sees option; denied player does notFilter regression
Server authorizationWrong job or remote request is rejectedAny unauthorized operation succeeds
Resource lifecycleRegistrations disappear/reappear as designed during coordinated restartDuplicate or missing registrations
IntegrationExisting menu/stash action and reconnect still workCaller 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.tar

Keep 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

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.

On this page

Leonida RP server website built with RPWebsite
RPWebsite

Advertisement · RPWebsite

Want a website for your server?

Launch a site with live player status, rules, and a join button in minutes.

Build your website