Support self-hosted github installations #2755

tz-lom · 2025-07-26T22:33:57Z

This PR enables support for self-hosted GitHub installations

I've tested it with the following setup

repo = Remotes.GitHub("XXX/YYY.git";host="AAA.com")

deploydocs(;
    deploy_config = Documenter.GitHubActions(
        "gh.asml.com",
        "https://pages.AAA.com/XXX/YYY"
    ),
    repo = repo,
    push_preview = true,

Both deployment and notification worked well

Was made during JuliaCon 2025 hackathon!

mortenpi · 2025-07-27T15:24:54Z

This looks fine to me! Could we also make sure that it's documented in the relevant docstrings please?

Documenter.jl/src/deployconfig.jl

Lines 295 to 316 in e972ea2

    
           """ 
        
               GitHubActions <: DeployConfig 
        
           Implementation of `DeployConfig` for deploying from GitHub Actions. 
        
           The following environment variables influences the build 
        
           when using the `GitHubActions` configuration: 
        
            - `GITHUB_EVENT_NAME`: must be set to `push`, `workflow_dispatch`, or `schedule`. 
        
              This avoids deployment on pull request builds. 
        
            - `GITHUB_REPOSITORY`: must match the value of the `repo` keyword to [`deploydocs`](@ref). 
        
            - `GITHUB_REF`: must match the `devbranch` keyword to [`deploydocs`](@ref), alternatively 
        
              correspond to a git tag. 
        
            - `GITHUB_TOKEN` or `DOCUMENTER_KEY`: used for authentication with GitHub, 
        
              see the manual section for [GitHub Actions](@ref) for more information. 
        
           The `GITHUB_*` variables are set automatically on GitHub Actions, see the 
        
           [documentation](https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables#default-environment-variables). 
        
           """

Documenter.jl/src/utilities/Remotes.jl

Lines 105 to 120 in e972ea2

    
           """ 
        
               GitHub(user :: AbstractString, repo :: AbstractString) 
        
               GitHub(remote :: AbstractString) 
        
           Represents a remote Git repository hosted on GitHub. The repository is identified by the 
        
           names of the user (or organization) and the repository: `GitHub(user, repository)`. E.g.: 
        
           ```julia 
        
           makedocs( 
        
               repo = GitHub("JuliaDocs", "Documenter.jl") 
        
           ) 
        
           ``` 
        
           The single-argument constructor assumes that the user and repository parts are separated by 
        
           a slash (e.g. `JuliaDocs/Documenter.jl`). 
        
           """

CHANGELOG.md

Co-authored-by: Morten Piibeleht <[email protected]>

tz-lom · 2025-07-27T23:34:56Z

This looks fine to me! Could we also make sure that it's documented in the relevant docstrings please?

I've updated documentation and hopefully - coverage.
But I want to mention that documentation is miss leading at this moment:

makedocs(
    repo = GitHub("JuliaDocs", "Documenter.jl")
)

The one above will probably work, but the one bellow will not (not because of my changes)

deploydocs(
    repo = GitHub("JuliaDocs", "Documenter.jl")
)

Is it just me reading documentation in a wrong way?

mortenpi · 2025-07-29T13:10:37Z

Do we have somewhere where we advertise passing e.g. GitHub() to deploydocs's repo=? I think right now we just accept a string there. I agree that it's a bit unfortunate that you can't just pass the object form there (we should probably expand that), but I am not sure there's anything misleading anywhere?

tz-lom · 2025-08-01T14:05:31Z

Do we have somewhere where we advertise passing e.g. GitHub() to deploydocs's repo=? I think right now we just accept a string there. I agree that it's a bit unfortunate that you can't just pass the object form there (we should probably expand that), but I am not sure there's anything misleading anywhere?

No, I can't find anything in documentation, but in output of the build I see this:

and with repo parameter in deploydocs this is totally misleading.

Anyway, I've double checked that this PR works in self-hosted environment, do you need anything else or you can merge it?

tz-lom · 2025-08-12T07:01:31Z

@mortenpi , can you review this please?

mortenpi

Sorry for the delay. Unfortunately, I do have a couple of questions. I think my main concern is to make sure this doesn't affect existing setups.

mortenpi · 2025-08-17T12:05:36Z

src/utilities/Remotes.jl

 """
-    GitHub(user :: AbstractString, repo :: AbstractString)
+    GitHub(user :: AbstractString, repo :: AbstractString, [host :: AbstractString])
    GitHub(remote :: AbstractString)


I took the liberty of removing host for the single-argument method. I think it would be better if it stays single-argument. If we want to add support for overriding the host, then let's figure out some syntax for the string, like github.selfhosted:Org/Repo.jl, which we can regex.

mortenpi · 2025-08-17T12:12:42Z

src/deployconfig.jl

+    github_api = get(ENV, "GITHUB_API_URL", "") # https://api.github.com
+
+    # Compute GitHub Pages URL from repository
+    parts = split(github_repository, "/")
+    github_pages_url = if length(parts) == 2
+        owner, repo = parts
+        "https://$(owner).github.io/$(repo)/"
+    else
+        ""
+    end
+
+    return GitHubActions(github_repository, github_event_name, github_ref, "github.com", github_api, github_pages_url)


If we hard-code github_host here, it feels like we should also hard-code the API URL? I also have a minor security concern here, where this could allow someone redirect the API calls somewhere (including the token) by somehow attacking the GITHUB_API_URL environment variable (for normal GitHub-hosted repos).

Suggested change

github_api = get(ENV, "GITHUB_API_URL", "") # https://api.github.com

# Compute GitHub Pages URL from repository

parts = split(github_repository, "/")

github_pages_url = if length(parts) == 2

owner, repo = parts

"https://$(owner).github.io/$(repo)/"

else

""

end

return GitHubActions(github_repository, github_event_name, github_ref, "github.com", github_api, github_pages_url)

# Compute GitHub Pages URL from repository

parts = split(github_repository, "/")

github_pages_url = if length(parts) == 2

owner, repo = parts

"https://$(owner).github.io/$(repo)/"

else

""

end

return GitHubActions(github_repository, github_event_name, github_ref, "github.com", "https://api.github.com", github_pages_url)

mortenpi · 2025-08-17T12:16:29Z

src/deployconfig.jl

+    github_repository = get(ENV, "GITHUB_REPOSITORY", "") # "JuliaDocs/Documenter.jl"
+    github_event_name = get(ENV, "GITHUB_EVENT_NAME", "") # "push", "pull_request" or "cron" (?)
+    github_ref = get(ENV, "GITHUB_REF", "") # "refs/heads/$(branchname)" for branch, "refs/tags/$(tagname)" for tags
+    github_api = get(ENV, "GITHUB_API_URL", "") # https://api.github.com


Is GITHUB_API_URL something that is configurable for a self-hosted instance, or can we assume it's api.$(host)?

There's also GITHUB_SERVER_URL, which could potentially be used for determining host automatically? Or would that not be reliable and/or two automagical?

I don't think we can assume anything about it, I don't know exactly if it is configurable but I would expect that it is as some orgs have strict rules about domain names

I need to check GITHUB_SERVER_URL , for some reason I haven't used that, don't know if it is because we don't have it or because I've missed it

if something like that exists I would prefer to used it indeed instead of specifying it manually

Note that GITHUB_API_URL is mentioned in the GitHub manual as a variable they set in GitHub Action workflows.

And in the corresponding enterprise docs at https://docs.github.com/en/[email protected]/actions/reference/workflows-and-actions/variables the example value given is http(s)://HOSTNAME/api/v3 -- so no, we can't just assume it is api.$(host) (I assume that's the URL one gest if one enables "subdomain isolation")

src/deployconfig.jl

tz-lom · 2025-09-03T09:11:31Z

@mortenpi I have number of issues in testing which I will address, but can you provide initial feedback about url parsing thing that I did based on your ideas, what do you think about it ?

fingolfin

Thank you, I think this is quite useful and sensible. I still have a bunch of comments :-)

fingolfin · 2025-10-30T20:39:18Z

src/deployconfig.jl


 Implementation of `DeployConfig` for deploying from GitHub Actions.

+For self-hosted GitHub installation use `GitHubActions(host, pages_url)` constructor


Suggested change

For self-hosted GitHub installation use `GitHubActions(host, pages_url)` constructor

For self-hosted GitHub installation use the `GitHubActions(host, pages_url)` constructor

fingolfin · 2025-10-30T20:39:57Z

src/deployconfig.jl

 Implementation of `DeployConfig` for deploying from GitHub Actions.

+For self-hosted GitHub installation use `GitHubActions(host, pages_url)` constructor
+to specify the host name and a **full path** to the GitHub pages location.


Is the "full path" referring to pages_url ? I find that confusing, a path is not an URL; maybe clarify the text?

review this description, seems that API update is not reflected here (is there constructor that takes host as argument?)

src/deployconfig.jl

fingolfin · 2025-10-30T20:53:56Z

src/deployconfig.jl

+    github_repository = get(ENV, "GITHUB_REPOSITORY", "") # "JuliaDocs/Documenter.jl"
+    github_event_name = get(ENV, "GITHUB_EVENT_NAME", "") # "push", "pull_request" or "cron" (?)
+    github_ref = get(ENV, "GITHUB_REF", "") # "refs/heads/$(branchname)" for branch, "refs/tags/$(tagname)" for tags
+    github_api = get(ENV, "GITHUB_API_URL", "") # https://api.github.com


Note that GITHUB_API_URL is mentioned in the GitHub manual as a variable they set in GitHub Action workflows.

And in the corresponding enterprise docs at https://docs.github.com/en/[email protected]/actions/reference/workflows-and-actions/variables the example value given is http(s)://HOSTNAME/api/v3 -- so no, we can't just assume it is api.$(host) (I assume that's the URL one gest if one enables "subdomain isolation")

fingolfin · 2025-10-30T21:12:15Z

src/deployconfig.jl

+    parts = split(github_repository, "/")
+    github_pages_url = if length(parts) == 2
+        owner, repo = parts
+        "https://$(owner).github.io/$(repo)/"


Of course you are just moving this around, and that's already a good step; so what I say below is not a change request, but a general thought (perhaps we should record it it into an issue)

Instead of hardcoding the pages URL like that (which won't if e.g. a custom domain name is used, as e.g. Documenter.jl does) one could also query the pages URL from the GitHub API. E.g. if the gh tool is installed:

$ gh api repos/JuliaDocs/Documenter.jl --jq '.homepage' https://documenter.juliadocs.org

But of course one also do that without, using just the github_api:

curl -s https://api.github.com/repos/JuliaDocs/Documenter.jl | jq -r '.homepage'

Obviously in Julia we'd use the JSON module, not jq, to parse this data.

That would be great, however I can't find any public API that will tell me where github pages are located.
homepage is not reliable and can point somewhere else
There is private api /repos/{owner}/{repo}/pages but it requires authentication.

src/utilities/Remotes.jl

fingolfin · 2025-10-30T21:43:40Z

test/deployconfig.jl

        # Regular tag build with GITHUB_TOKEN
        withenv(
-            "GITHUB_EVENT_NAME" => "push",
+            "GITHUB_EVENT_NAME" => "push", "GITHUB_SERVER_URL" => "github.com",


Let's keep this to one per line?

Suggested change

"GITHUB_EVENT_NAME" => "push", "GITHUB_SERVER_URL" => "github.com",

"GITHUB_EVENT_NAME" => "push",

"GITHUB_SERVER_URL" => "github.com",

and then the same everywhere below.

check that this is not because of auto format and do the change uniformly

fingolfin · 2025-10-30T21:46:23Z

test/deployconfig.jl

+            logger = SimpleLogger(buffer, Logging.Debug)
+            with_logger(logger) do
+                withenv(
+                    "GITHUB_EVENT_NAME" => "push", "GITHUB_SERVER_URL" => "github.com",


Suggested change

"GITHUB_EVENT_NAME" => "push", "GITHUB_SERVER_URL" => "github.com",

"GITHUB_EVENT_NAME" => "push",

"GITHUB_SERVER_URL" => "github.com",

Co-authored-by: Max Horn <[email protected]>

…fhosted_github

tz-lom force-pushed the feature/support_selfhosted_github branch 2 times, most recently from 60c5931 to f3853c9 Compare July 27, 2025 14:50

Support self-hosted github installations

ef38eb7

tz-lom force-pushed the feature/support_selfhosted_github branch from f3853c9 to ef38eb7 Compare July 27, 2025 14:50

mortenpi reviewed Jul 27, 2025

View reviewed changes

CHANGELOG.md Show resolved Hide resolved

tz-lom and others added 2 commits July 27, 2025 14:19

Update CHANGELOG.md

407d4b9

Co-authored-by: Morten Piibeleht <[email protected]>

Update documentation and improve coverage

de1721f

Fix flaky test

438901a

tz-lom force-pushed the feature/support_selfhosted_github branch from 2964c67 to 438901a Compare July 28, 2025 01:18

tz-lom requested a review from mortenpi July 29, 2025 12:40

mortenpi added 3 commits August 17, 2025 14:07

fix changelog

be69eef

fix ws

bc84016

cleanup

5fb85ef

mortenpi reviewed Aug 17, 2025

View reviewed changes

mortenpi and others added 4 commits August 17, 2025 15:20

Merge branch 'master' into feature/support_selfhosted_github

285c286

Select host based on environment variable

a1fa597

Fix test and update docstring

c992c64

Provide full path to the object name

ed5eeba

tz-lom and others added 2 commits September 5, 2025 19:29

Merge branch 'master' into feature/support_selfhosted_github

77ab55a

Address smaller issues

dc9337f

fingolfin reviewed Oct 30, 2025

View reviewed changes

fingolfin added the Status: Waiting for Author The issue or pull request needs some action by its author label Oct 31, 2025

tz-lom and others added 2 commits November 3, 2025 23:53

Apply suggestions from code review

0e268b4

Co-authored-by: Max Horn <[email protected]>

Merge remote-tracking branch 'origin/master' into feature/support_sel…

47fecbe

…fhosted_github


		Implementation of `DeployConfig` for deploying from GitHub Actions.

		For self-hosted GitHub installation use `GitHubActions(host, pages_url)` constructor

	"GITHUB_EVENT_NAME" => "push", "GITHUB_SERVER_URL" => "github.com",
	"GITHUB_EVENT_NAME" => "push",
	"GITHUB_SERVER_URL" => "github.com",

Support self-hosted github installations #2755

Are you sure you want to change the base?

Support self-hosted github installations #2755

Conversation

tz-lom commented Jul 26, 2025

Uh oh!

mortenpi commented Jul 27, 2025

Uh oh!

Uh oh!

tz-lom commented Jul 27, 2025

Uh oh!

mortenpi commented Jul 29, 2025

Uh oh!

tz-lom commented Aug 1, 2025

Uh oh!

tz-lom commented Aug 12, 2025

Uh oh!

mortenpi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

tz-lom commented Sep 3, 2025

Uh oh!

fingolfin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fingolfin Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

fingolfin Oct 30, 2025 •

edited

Loading