welcome/README.md

Welcome to the ZapBurrito Studios' Gitea instance!

Hey, glad you're here! This repo is your starting point — it covers everything you need to know to get set up and make the most of this instance. Give it a read through, it won't take long.

---

Getting Set Up

SSH Key

The easiest way to interact with repos is over SSH. If you haven't already:

1. Generate a key if you don't have one:

   ssh-keygen -t ed25519 -C "your_email@example.com"
   

2. Copy your public key (~/.ssh/id_ed25519.pub)
3. Go to Settings → SSH / GPG Keys → Add Key and paste it in

Test it with:

ssh -T git@<instance-address>

Personal Access Token

You'll need a token for API access or tooling (like tea CLI, scripts, etc.):

1. Go to Settings → Applications → Generate New Token
2. Give it a descriptive name and select the scopes you need
3. Save it somewhere safe — you won't be able to see it again

---

Requesting Repo Access

If you need access to a repo you can't see or collaborate on, just reach out directly:

• DM or email the admin to request access
• Mention the repo name and what kind of access you need (read / write / admin)

You'll get added as a collaborator or to the relevant team.

---

Branch Protection & PR Rules

All main branches are protected — you can't push directly to main. Everything goes through a pull request:

• Create a feature branch off main
• Push your changes and open a PR
• PRs require at least one review before merging
• Once approved, squash or merge — your call

This applies to repos on this instance and any mirrored GitHub repos. Keep it clean! 🧹

---

CI/CD & Actions

This instance runs a self-hosted Gitea Actions runner, targeting Rust workflows. It supports:

• Standard Rust builds (stable toolchain)
• Cross-compilation targets: thumbv6m-none-eabi (RP2040), STM32, and x86_64-unknown-linux-musl
• Workflows live in .gitea/workflows/ in your repo (same syntax as GitHub Actions)

A minimal example to get you started:

# .gitea/workflows/build.yml
name: Build

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: cargo build --release

All current runners

Checkout the gitea-runners repo for a list of all currently available runners, and their targeting tags

---

Requesting a Custom Runner

Got a workflow that needs something the current runner doesn't support? You can request a custom runner — here's how it works:

Option 1 — Just open an issue

If you're not sure what the Dockerfile should look like, open an issue in the gitea-runners repo describing:

• What your workflow needs (language, tools, dependencies)
• Which repos would use it
• Any relevant labels your workflow would target

Option 2 — Build it yourself (preferred 🙌)

If you know what you need, contribute the runner directly:

1. Fork the gitea-runners repo
2. Create a new folder for your runner, e.g. runners/my-custom-runner/
3. Add a Dockerfile and a brief README.md explaining what it provides
4. Open a Pull Request back to main with a clear description

Once the PR is reviewed and merged, the runner gets built and registered on the server. Your workflow can then target it by label:

jobs:
  my-job:
    runs-on: my-custom-runner

Tip: Keep Dockerfiles lean — base off debian:bookworm-slim or alpine where possible, and only install what the workflow actually needs.

---

Need Help?

Something broken, confusing, or missing from this guide? Reach out directly — happy to help sort it out.

Welcome aboard! 🚀