Skip to content

Maintainer Onboarding

Quick-start checklist for new maintainers and release owners.

1. Set the GitHub Social Preview image

GitHub's social preview (the image shown when sharing a link on Slack, Twitter/X, LinkedIn, etc.) must be a rasterized PNG — it cannot be an SVG.

One-time setup steps:

# Prerequisites: Inkscape or rsvg-convert or ImageMagick (cairosvg also works)

# Option A — Inkscape (recommended, most faithful SVG rendering)
inkscape assets/social-preview.svg \
  --export-type=png \
  --export-filename=assets/social-preview.png \
  --export-width=1280

# Option B — rsvg-convert (librsvg, fast, good font support)
rsvg-convert -w 1280 assets/social-preview.svg -o assets/social-preview.png

# Option C — cairosvg (Python)
pip install cairosvg
python3 -c "import cairosvg; cairosvg.svg2png(url='assets/social-preview.svg', write_to='assets/social-preview.png', output_width=1280)"

Then upload:

  1. Go to github.com/adamdost-0/linux-update-cds → Settings (top nav).
  2. Scroll to Social preview section.
  3. Click Edit → Upload an image….
  4. Select assets/social-preview.png (1280 × 640 px).
  5. Click Save changes.

The rasterized PNG does not need to be committed to the repository — it is only needed for the GitHub UI upload.

2. Verify repository topics and description

gh repo view adamdost-0/linux-update-cds --json description,topics

Expected topics: pulp, air-gap, azure-government, ubuntu, apt, solution-accelerator, linux, mirror, disconnected, iac, bicep.

To add a missing topic:

gh repo edit adamdost-0/linux-update-cds --add-topic <topic>

3. Branch protection

Ensure the default branch (main) has:

  • Require pull request reviews before merging (at least 1 approver).
  • Require status checks (CI, CodeQL, Gitleaks) to pass.
  • Require branches to be up to date before merging.
  • Restrict who can push directly to main.

Configure under Settings → Branches → Branch protection rules.

4. Enable the documentation site (GitHub Pages)

  1. Go to Settings → Pages in your GitHub repository.
  2. Under Source, select GitHub Actions (not the legacy "Deploy from a branch" option).
  3. Click Save.

The docs-publish.yml workflow builds and deploys the MkDocs site automatically on every push to main that touches docs/**, mkdocs.yml, requirements-docs.txt, README.md, or the workflow file itself.

The site is published at:

https://<owner>.github.io/linux-update-cds/

First deployment

After enabling Pages, trigger the first build by either:

  • Pushing any change to main that matches the paths filter in docs-publish.yml, or
  • Going to Actions → docs → Run workflow and triggering manually.

Custom domain (optional)

To use a custom domain:

  1. Create docs/CNAME with a single line containing the domain: 
    docs.example.com
  2. Configure your DNS provider with the appropriate CNAME or ALIAS record pointing to <owner>.github.io.
  3. In Settings → Pages, enter the custom domain and enable Enforce HTTPS.

Local docs build

pip install -r requirements-docs.txt
mkdocs serve          # live-reload at http://127.0.0.1:8000
mkdocs build --strict # full build with strict link checking