Jobs
Copy Job

📨 Copy Job

Copy jobs replicate snapshots from one repository to another. This is useful for creating off-site backups or maintaining multiple backup copies. Jobs are defined inside a pipeline.

Configuration Structure

pipelines:
  - name: my-pipeline
    jobs:
      - type: copy
        name: string                    # Required: Job name (unique within pipeline)
        from: string                    # Required: Source repository name
        to: string                      # Required: Target repository name
        options:                        # Optional: Restic copy options
          key: value
        hooks:                          # Optional: Lifecycle hooks
          before: []string
          success: []string
          failure: []string

Required Fields

type

Must be "copy".

name

Identifier for the job within the pipeline. Used in logs and CLI as pipeline/job.

name: offsite-copy
name: documents-to-remote

from

Name of the source repository (must be defined in repositories section).

from: local-repo
from: primary-backup

to

Name of the target repository (must be defined in repositories section).

to: remote-repo
to: secondary-backup

Options

The options field accepts any restic copy option. Common options:

Filter by Tags

Copy only snapshots with specific tags:

options:
  tag:
    - important
    - documents
    - daily

Filter by Hostname

Copy only snapshots from specific host:

options:
  host: my-server

Filter by Paths

Copy only snapshots containing specific paths:

options:
  path: /home/user/Documents

See: Restic Copy Documentation (opens in a new tab) for complete list of options.

Hooks

Execute custom commands at different stages:

hooks:
  before:
    - echo "Starting copy operation: $CRESTIC_JOB_NAME"
  success:
    - echo "Copy completed successfully: $CRESTIC_JOB_NAME"
  failure:
    - echo "Copy failed: $CRESTIC_JOB_NAME - $CRESTIC_ERROR" >&2

Environment variables available in hooks:

  • CRESTIC_JOB_NAME - Qualified job name (pipeline/job)
  • CRESTIC_EXIT_CODE - Exit code of the operation
  • CRESTIC_ERROR - Error message (only in failure hooks)

See Hooks for more details.

Complete Example

pipelines:
  - name: documents-nightly
    cron: "0 2 * * *"
    jobs:
      - type: backup
        name: local-backup
        from: [/home/user/Documents]
        to: local-repo
 
      - type: copy
        name: offsite-copy
        from: local-repo
        to: remote-repo
        options:
          tag:
            - documents
            - important
          host: my-server
        hooks:
          before:
            - echo "Starting copy: $CRESTIC_JOB_NAME"
          success:
            - echo "Copy completed: $CRESTIC_JOB_NAME"
          failure:
            - echo "Copy failed: $CRESTIC_JOB_NAME - $CRESTIC_ERROR" >&2

Running Copy Jobs

Run Entire Pipeline

crestic backup --pipeline documents-nightly

Run Specific Copy Job

crestic backup --job documents-nightly/offsite-copy

Note: Copy jobs are executed using the backup command, not a separate copy command.

Run All Jobs

crestic backup --all

What Happens During Copy

The copy operation:

  1. Runs before hooks (if configured)
  2. Initializes source and target repositories if they do not exist yet
  3. Copies snapshots from source to target repository
  4. Verifies integrity — runs restic check on the target repository
  5. Applies retention policy — runs restic forget with the target's forget_options
  6. Runs success or failure hooks based on outcome

Pipeline-level healthcheck pings (when enabled) wrap the whole pipeline, not individual copy jobs. See Healthchecks.

Error Handling

Jobs in a list run sequentially (fail-fast). If one job fails:

  • The error is logged and returned immediately
  • Remaining jobs in the same list are not executed

When running multiple pipelines, each pipeline still runs even if a previous pipeline failed; pipeline-level errors are combined at the end.

See Also

Backup JobRepositories