- [Add new image](#add-new-image)
- [Open new region](#open-new-region)
- [Fast Image Delivery](#fast-image-delivery)
- [File Structure](#file-structure)
- [FAQ](#faq)

## Add new image

1. Add the image to the `image-sync-dev.yaml`(For dev environment) or `image-sync-prod.yaml`(For prod environment) file. 
([learn how to configure it in detail](docs/configurations.md))
   1. If the image is only needed for a specific region, add it to the `targetRegistries`->`repositories` section
   2. If the image is needed for all regions, add it to the `commonRepositories` section of the `repositorySets` section, it will be synced to all target registries including the `commonRepositories`.
2. Create a pull request to the `main` branch
3. Ask the reviewer to approve the pull request
4. Once pull request is merged, new images sync will start immediately, you can check the sync progress here: [Github Action](https://github.com/tidbcloud/docker-image-controller/actions)

## Fast Image Delivery

Use this workflow to quickly sync specific next-gen images to dev or prod environments without waiting for the scheduled sync or creating a PR.

### How to use

- Option 1: Comment-triggered on Issues/PRs
  - Who can run: org MEMBERS/OWNERS and repo COLLABORATORS
  - Add a comment with the first line as:
    - `/fid env=<dev|prod> [cid=<uuid>]`
    - or: `/fid <dev|prod> [cid=<uuid>]`
  - Then list images (one per line) on the following lines in the format `repository:tag`
  - Example:
    - `us.gcr.io/pingcap-public/tidbx/pd:master-next-gen`
    - `us.gcr.io/pingcap-public/tidbx/tidb:release-nextgen-20241022`
  - Behavior:
    - The dispatcher reacts to your comment with :rocket: and dispatches the Fast Image Delivery workflow
    - The workflow validates and syncs images, then reacts :hooray: on success or :confused: on failure and comments back with a summary (including target image URLs)
    - If `cid` is omitted, a Correlation-ID is auto-generated and included in the reply

- Option 2: Manual dispatch via Actions
  1. Go to [Fast Image Delivery workflow](https://github.com/tidbcloud/docker-image-controller/actions/workflows/fast-image-delivery.yml)
  2. Click "Run workflow"
  3. Fill in the required inputs:
     - **Images**: One or multiple images to sync (one per line), in the format `repository:tag`
       - Example: `us.gcr.io/pingcap-public/tidbx/pd:master-next-gen`
       - For multiple images, use newlines to separate them
     - **Environment stage**: Select either `dev` or `prod`
  4. Click "Run workflow" to start the sync

### How it works

1. **Validation**: The workflow validates that the input images match the sync rules defined in `image-sync-nextgen-{env-stage}.yaml`
2. **Sync**: If validation passes, only the specific images provided as input are synced to the target registries using `regctl image copy`
3. **Output**: The workflow outputs the synced target image URLs in the job summary

**Note**: This workflow syncs only the specific images you provide, not all images in the config file.

### Example

**Input:**
```
us.gcr.io/pingcap-public/tidbx/pd:master-next-gen
us.gcr.io/pingcap-public/tidbx/tidb:release-nextgen-20241022
```

**Environment:** `dev`

**Output:**
```
385595570414.dkr.ecr.us-west-2.amazonaws.com/tidbcloud/pd:master-next-gen
tidbcloud-dev-registry.ap-southeast-1.cr.aliyuncs.com/tidbcloud/pd:master-next-gen
385595570414.dkr.ecr.us-west-2.amazonaws.com/tidbcloud/tidb:release-nextgen-20241022
tidbcloud-dev-registry.ap-southeast-1.cr.aliyuncs.com/tidbcloud/tidb:release-nextgen-20241022
```

### Notes

- Only images defined in the `image-sync-nextgen-{env-stage}.yaml` configuration file can be synced
- Image tags must match the allowed patterns defined in the configuration
- If validation fails, the workflow will stop and no images will be synced

## Open new region

(Only if you have a new account / region / registry)
1. Add the container registry of the new region to the `image-sync-xxx.yaml` file. 
([learn how to configure it in detail](docs/configurations.md))
   1. Add the new region to the `targetRegistries` section
   2. include the `commonRepositories` section in the `includeRepositorySets` section if needed
2. Create a pull request to the `main` branch
3. Ask the reviewer to approve the pull request
4. Once pull request is merged, new images sync will start immediately, you can check the sync progress here: [Github Action](https://github.com/tidbcloud/docker-image-controller/actions)

## File Structure 
- `.github/workflows/fast-image-delivery.yml` - validates and syncs specific next-gen images; can be run manually or via the dispatcher; posts summary and reactions when invoked by comment
- `.github/workflows/fast-image-delivery-dispatch.yml` - listens for `/fid` comments and dispatches `fast-image-delivery.yml` with inputs (images, `env_stage`, `reply_issue_number`, `reply_comment_id`, `reply_actor`, `correlation_id`)
- `.github/workflows/image-sync-xxx.yml` - github actions to sync images to the clouds
  - All involved container registry should be authenticated here
  - It runs `./regsync-cloud-linux-amd64 once -c image-sync-dev.yaml --cloud` to sync the images to the clouds
- `image-sync-xxx.yaml` - the configuration file for `regsync-cloud` - learn how to configure it [here](docs/configurations.md)
  - It defines the source and target container registry
  - It defines the repositories to be synced
  - It defines the tags allowed/denied to be synced

## FAQ