Skip to content

docs: rewrite GitHub integration page as step-by-step tutorial#2512

Open
marcel-rbro wants to merge 4 commits into
masterfrom
docs/github-integration-tutorial
Open

docs: rewrite GitHub integration page as step-by-step tutorial#2512
marcel-rbro wants to merge 4 commits into
masterfrom
docs/github-integration-tutorial

Conversation

@marcel-rbro
Copy link
Copy Markdown
Contributor

@marcel-rbro marcel-rbro commented May 7, 2026

Closes #2492

Summary

Rewrites sources/platform/integrations/programming/github.md:

  • Restructured as Prerequisites → Create an Actor from a GitHub repository (Steps 1-3) → Build automatically on every push → Create a GitHub issue when an Actor run fails (Steps 1-4) → Resources.
  • Updated the new-Actor walkthrough to match the current Apify Console UI ("Let's build a new Actor!" page, with GitHub listed directly under Link a Git repository - no intermediate provider modal).
  • Replaced the bare YouTube embed for the failure-issue flow with a written tutorial: generate a fine-grained GitHub PAT, add an ACTOR.RUN.FAILED HTTP webhook on the Actor, set the headers/payload templates to call POST /repos/{owner}/{repo}/issues, save and test. Kept the original video as a "Video walkthrough" subsection.
  • Refreshed two screenshots: apify-git-repository.png (the new-Actor page) and integrations-tab.png (the Add integration page; this image is also reused by slack.md and webhooks/index.md).
  • Removed the now-unused apify-git-provider-select.png (the provider-picker modal no longer exists).
  • Adopted the current intro convention (plain prose + <ThirdPartyDisclaimer />, no bold one-liner or --- rule), matching recent integration pages (Pipedream, Snowflake, Manus, viaSocket, x402).

Reviewer question

There's an inline MDX comment in the Build automatically on every push section asking whether the native "Link a Git repository" flow already wires up auto-builds (the panel's helper text suggests it does). If so, the manual GitHub webhook recipe currently in that section is the legacy path - please confirm and let me know whether to keep it as-is, replace it with a one-line note, or keep both with a clarifying intro.

Test plan

  • pnpm lint:md passes for the changed file
  • vale "sources/platform/integrations/programming/github.md" reports 0 errors
  • All cross-link slugs verified to exist (/platform/actors/development/deployment/continuous-integration, /platform/actors/development/deployment/source-types#private-repositories, /platform/integrations/webhooks/events, /platform/integrations/webhooks/actions)
  • pnpm build passes (no broken links, frontmatter valid)
  • Page renders correctly in dev server: prereqs, all numbered steps, admonitions, code blocks, and the embedded YouTube iframe
  • Slack and Webhooks pages still render the (replaced) integrations-tab.png correctly

🤖 Generated with Claude Code

…utorial

Restructures the GitHub integration page into prerequisites, a numbered
"Create an Actor from a GitHub repository" walkthrough that matches the
current "Let's build a new Actor!" UI, and a written tutorial for opening
a GitHub issue via Apify webhook + the GitHub REST API. Replaces the bare
YouTube embed and refreshes the new-Actor and Integrations-tab screenshots.

Closes #2492

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@github-actions github-actions Bot added the t-docs Issues owned by technical writing team. label May 7, 2026
@marcel-rbro marcel-rbro changed the title docs(integrations): rewrite GitHub integration page as step-by-step tutorial docs: rewrite GitHub integration page as step-by-step tutorial May 7, 2026
@marcel-rbro marcel-rbro marked this pull request as ready for review May 7, 2026 09:56
Comment thread sources/platform/integrations/programming/github.md Outdated
@patrikbraborec
Copy link
Copy Markdown
Contributor

Also, it would be great to have preview to check it. :) Anyway, thanks! It looks good.

@TC-MO
Copy link
Copy Markdown
Contributor

TC-MO commented May 11, 2026

Previews are broken atm (seems connected to npm > pnpm migraton) @vladfrangu is aware and working on fix

@vladfrangu
Copy link
Copy Markdown
Member

I'm gonna piggy back off of this PR to test out the fixed previews, pls stand by and sorry in advance

@apify-service-account
Copy link
Copy Markdown
Contributor

apify-service-account commented May 11, 2026

✅ Preview for this PR (commit a3c57361) is ready at https://pr-2512.preview.docs.apify.com (see action run).

@patrikbraborec
Copy link
Copy Markdown
Contributor

One note -> let's probably remove the video? cc. @TC-MO

@TC-MO
Copy link
Copy Markdown
Contributor

TC-MO commented May 11, 2026

Yes, I'll never say no to video pruning from docs :D how urgent this is? Can it wait until Marcel is back from off time next week, or should I take over to have this shipped this week?

@patrikbraborec
Copy link
Copy Markdown
Contributor

I guess it can wait, we are refactoring the UI in the meantime, so maybe it will need to be updated. :D

…page

Remove the inline reviewer question (manual webhook recipe confirmed as the
current path) and drop the video walkthrough per reviewer request.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@marcel-rbro
Copy link
Copy Markdown
Contributor Author

marcel-rbro commented May 19, 2026

I'm back now, applied the suggested changes. Also, @vladfrangu did I stand by for long enough and can I close this PR whenever ready?

@vladfrangu
Copy link
Copy Markdown
Member

Oh yeah, testing was done and it works now! Feel free to proceed as normal whichever way that is

Comment thread sources/platform/integrations/programming/github.md Outdated
Match the convention in sources/platform/integrations/programming/
(api.md does not use the disclaimer either) per review feedback.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Copy link
Copy Markdown
Contributor

@TC-MO TC-MO left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, substantial improvement over the original.

A few changes to address before merging.

Non-blocking tangent (not for this PR):

We should rethink our use of click more broadly across the docs. Either prefer select outright or formalize a click (buttons) vs select (list choices) distinction.

Comment thread sources/platform/integrations/programming/github.md Outdated
Comment thread sources/platform/integrations/programming/github.md Outdated
Comment thread sources/platform/integrations/programming/github.md
Comment thread sources/platform/integrations/programming/github.md Outdated
Comment thread sources/platform/integrations/programming/github.md Outdated
- Move Prerequisites under "Create an Actor from a GitHub repository"
- Clarify the API dropdown / "API endpoints" selection in Console
- Replace "tell GitHub" with "specify" to avoid anthropomorphizing
- Use input-induced failure as the test example (abort fires
  ACTOR.RUN.ABORTED, not ACTOR.RUN.FAILED)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@marcel-rbro marcel-rbro requested a review from TC-MO May 21, 2026 14:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

t-docs Issues owned by technical writing team.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Improve GitHub integration page

5 participants