actions/README.md

# scotty-git actions

Shared Forgejo Actions that any repository on **git.scotty-world.com** can use.

| Action | What it does |
|---|---|
| [`kaniko-build`](#kaniko-build) | Build a container image from your repository and push it to a registry |

Actions on this server are referenced by their **full URL**. Short names such as `actions/checkout`
still resolve to `data.forgejo.org`, as usual.

---

## kaniko-build

Builds a Docker/OCI image from the repository your job checked out, using
[Kaniko](https://github.com/GoogleContainerTools/kaniko), and pushes it to the registry you choose.

**Why Kaniko and not `docker build`:** the scotty-git runner is a shared, long-lived machine. Giving
workflows the Docker daemon would hand every workflow root access to that machine and leave image
layers on its disk. Kaniko builds inside the step's own container instead: no root, no privileged
mode, nothing left behind. The build happens the same way as on a GitHub-hosted runner; only the
engine differs.

### Quick start: push to scotty-git's own container registry

No cloud account needed. Create a token at **Settings → Applications** with the
`write:package` scope, and save it in your repository as the secret `REGISTRY_TOKEN`
(**Settings → Actions → Secrets**). Then:

```yaml
# .forgejo/workflows/image.yml
name: Build image
on:
  push:
    branches: [main]

jobs:
  image:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: https://git.scotty-world.com/scotty-git/actions/kaniko-build@v1
        with:
          destination: git.scotty-world.com/${{ github.repository }}:${{ github.sha }}
          username: ${{ github.actor }}
          password: ${{ secrets.REGISTRY_TOKEN }}
```

The image appears under your repository's **Packages** tab.

### Google Artifact Registry

Use a service account that can push to **your** repository only (role `Artifact Registry Writer`
granted on that one repository, nothing project-wide). Save its JSON key as a secret in **your**
repository, never at organisation or instance level:

```yaml
      - uses: https://git.scotty-world.com/scotty-git/actions/kaniko-build@v1
        with:
          destination: asia-south1-docker.pkg.dev/my-project/my-repo/my-app:${{ github.sha }}
          gcp_key_json: ${{ secrets.GCP_AR_PUSH_KEY }}
          cache_repo: asia-south1-docker.pkg.dev/my-project/my-repo/my-app-cache
```

### Docker Hub, GitHub Container Registry, others

```yaml
        with:
          destination: docker.io/my-user/my-app:1.2.3
          username: my-user
          password: ${{ secrets.DOCKERHUB_TOKEN }}
```

### Inputs

| Input | Default | Description |
|---|---|---|
| `destination` | | Image reference(s), separated by commas or new lines. Required unless `push` is `false`. |
| `context` | `.` | Build context, relative to the repository root. |
| `dockerfile` | `Dockerfile` | Dockerfile path, relative to the repository root. |
| `push` | `true` | `false` builds without pushing, e.g. to check that a PR still builds. |
| `registry` | host of the first destination | Registry the credentials are for. |
| `username` / `password` | | Registry login. Always pass the password from a secret. |
| `gcp_key_json` | | Google service-account key JSON, instead of username/password. |
| `cache_repo` | | Registry repository for the layer cache. Speeds up rebuilds; stored in the registry, not on the runner. |
| `build_args` | | One `KEY=VALUE` per line. |
| `extra_args` | | Extra Kaniko flags, space-separated (advanced). |

**Output:** `digest`, the sha256 digest of the pushed image.

### Good to know

- **Check out first.** The action builds whatever `actions/checkout` put in the workspace.
- **Credentials stay yours.** This action stores no credentials. Each repository passes its own
  secret, and the login exists only inside the step's container for the length of the build.
- **The runner is shared.** Image builds take a few minutes on a small machine and other jobs
  queue behind them. Use `cache_repo` to keep rebuilds short.
- **The Kaniko version is pinned** (v1.23.2, by digest) in `kaniko-build/Dockerfile`, so a build
  tool update can never change your builds without a reviewed change here.
- **Versions:** use `@v1` to get compatible fixes. Breaking changes get a new major tag.

### Runner limits (all workflows on scotty-git)

Every job on the shared scotty-git runner is limited to **1.5 GB of memory**, so that no workflow can
take down the git server it runs next to. Each job can read the limit from the environment variable
`SCOTTY_GIT_JOB_MEMORY_LIMIT`.

**If a step fails with `exit code 137`**, it was stopped because it used more than 1.5 GB. Common
fixes: run tests with fewer parallel workers, avoid loading whole datasets into memory, or split the
job. `kaniko-build` prints this explanation itself. For other steps the runner can only report the
exit code, so this is the place to look it up. If your workload genuinely needs more, ask the
scotty-git admins (every memory stop is logged on the runner: `journalctl -t ci-memory-limit`).

### Changing this action

Open a pull request. The `Self-test kaniko-build` workflow builds a small test image with your
change before it can affect anyone's workflow.