Skip to end of metadata
Go to start of metadata

You can use Bitbucket to host a static website. A static website contains coded HTML pages with fixed content. Websites hosted in this way have the bitbucket.org domain in their URL, for example, http://tortoisehg.bitbucket.org.  Another example, is the site maintained by the Bitbucket 101 tutorial that lists favorite quotes by Bitbuckians.  

Publishing a static website on Bitbucket requires you to combine your account's name with the bitbucket.org domain suffix. So, your account's name must be acceptable to your DNS service. Upper case characters and special characters are typically not acceptable. For example, if your account's name is happy_cat, you would need to create a new account with a username of happycat to use this feature because underscores are not allowed in DNS hostnames. Your repository name would be happycat.bitbucket.org and the published static website is reached by this URL: http://happycat.bitbucket.org

The following topics appear on this page: 

Icon

If you have an existing domain you can have the landing page of its website open onto your Bitbucket account page (http://bitbucket.org/accountname). To to do this, see Associate an existing domain with an account.

Configure a Website for Hosting

To use this feature, do the following:

  1. Log into your Bitbucket account.
  2. Create a repository and making sure to Name it using the following format:
    accountname
    .bitbucket.org

    The repository name needs to include the trailing bitbucket.org. For example, if your accountname is tutorials (1) your repository Name should be this tutorials.bitbucket.org (2)
  3. Clone your repository to your local system.
  4. Create  an index.html file in the repository root.
    Keep in mind the names are case sensitive; Bitbucket treats index.html and Index.html as different file names. Make sure your file is named index.html – all lowercase.
  5. Add index.html file to your repository, commit the change, and push the result to Bitbucket.
  6. Navigate to the  http://accountname.bitbucket.org site.
    For example, if your username is is tutorials you would navigate to http://tutorials.bitbucket.org. The system displays the HTML in the site's index.html.  

Technical Features and Limitations of this Feature

Static websites on Bitbucket support the following features:

  • Embedding images and other media. 
  • Inclusion of JavaScripts in your HTML pages.
  • Blog comments by embedding Disqus in your site.

This feature turns a repository into a plain static webserver that uses the repository's root as the web root. Bitbucket does not support the use of HTTPS with this feature; you cannot log into the site. The system does not issue cookies for these domains. Server-side scripts or code are not supported. You cannot use PHP or other server-side scripting languages on the site.

Finally, Atlassian injects a rum.js script into each Bitbucket website. This script captures internal web analytics and statistics.

Hosting Multiple Projects Under a Single Website

You may have multiple projects that you want to host from the same Bitbucket websites, you can do this by placing each project in a repository subdirectory. In this example, you would want to organize things such that you can point users to:

  • http://accountname.bitbucket.org/subdir1forproject1
  • http://accountname.bitbucket.org/subdir2forproject2
  • http://accountname.bitbucket.org/subdir3forproject3

Each project sub-sirectory would act as a self-contained website with its own index.html.

Bitbucket is forgiving with regard to trailing slashes: a request to http://accountname.bitbucket.org/projectX/ with result in projectX/index.html being served (if such a file exists), regardless of whether the trailing slash is included in the URL. This presents a problem with relative links. projectX/index.html, for example, could include a relative link to a README:

If the trailing slash were omitted from the URL, this link would resolve to http://accountname.bitbucket.org/README.html rather than http://accountname.bitbucket.org/projectX/README.html. You can account for this by adding the following JavaScript to the index.html page:

See the Bitbucket issue #3856 for more information. For the threaded discussion that served as a basis for this section see the attached PDF.

Public and Private Repositories and Static Websites

The static website you create with this feature is just like any other website on the Internet — anyone with the URL (address) can visit and view your static website.  The underlying Bitbucket repository can be a public repository or a private repository.  This means if your Bitbucket repository is private, users can still visit and view the static website.  The same is true if the underlying repository is public.

58 Comments

  1. Anonymous

    What an absolutely superb facility! I was looking around for some static hosting for some technical articles after my regular ISP was complaining after one got a flurry of interest and blew my months bandwidth quota in a few hours, but couldn't find anything which didn't want to treat me like an idiot.  I already use bitbucket for source control, and this'll let me bring supporting website materials into the same fold.  And using hg to update the live version of the site is just so much nicer than messing around with FTP on my ISP's pages.  Nice!

  2. Anonymous

    What a very clear documentation about this topic ! Just like every Atlassian's docs. Congrats guys that's what good job is ^^

  3. Anonymous

    Awesome! One question though: this doesn't seem to work with submodules, am I mistaken? Will this be added as a feature, or could I create a ticket somewhere?

     

    1. I'm not sure I understand what you mean by "submodules" – you can create sub projects.  You can create a ticket at the Bitbucket issue tracker.

    2. Anonymous

      Also would like to know an answer on this question..

       

      Maybe Erik van Zijst [Atlassian] can help us?

  4. Does Bitbucket pages supports hosting and serving SWF files (using embed tag or swfobject) ?

    1. Ok not really reactive...

      I have tested and Bitbucket pages cannot be used to display SWF files embeded in an HTML wrapper.

      I have create an issue here : https://bitbucket.org/site/master/issue/6397/

  5. Maybe it is a good idea to check the user names being created against a forbidden names list.
    I chose the user name "cdn". Created a repo cdn.bitbucket.org for a static website. And I just wasted 12+ hours trying to find out why I got the infamous "Access Denied" XML message from AWS on cdn.bitbucket.org/nd/index.html. Until I found out that cdn.bitbucket.org was already taken. No points for guessing by whom. (smile)
    I'm going to delete the repo and profile and give it another crack.

  6. Is posible configure a Octopress site in Bitbucket?. I have a tumblr blog (with Octopress theme) and need to migrate to an static website. In github is posible, but never works for me...

    Many thanks.

    1. We don't explicitly support it or not.  You'd have to try it.  The limitations on this page cover the known limitations; we don't support Disqus comments on blogs

    2. Anonymous

      Because octopress generates static websites as a final result, yes, this sounds like it would work fine (although I have not tried it).  

      IIRC, OP uses a rake file to automate some of the deployment steps, which my not configure the branch names correctly though, so the correct question would be, does octopress support bitbucket.  That being said, simply committing the final results so they work with bitbucket, sounds like it should work fine.

  7. Can a private repo be hosted on bitbucket.org as a static website, and require HTTP auth and only allow viewers with credentials

  8. Thanks! 

    Any plans on adding such a feature? maybe as a paid plan?

  9. As Bitbucket users, do we have access to rum.js analytics results (e.g dashboard or something else) ? Thanks

    1. rum.js is used by our internal monitoring only and cannot be made available externally.

  10. If PHP is not allowed, does that mean a contact form would not work?

    1. Hi Justin, if it is written in PHP it wouldn't.  There is nothing that precludes you from trying.

  11. Anonymous

    Are there any restrictions about usage when hosting a site through bitbucket?

    1. Well, there are limitations as you see from the page.  I'm not sure what you mean by usage – that is a broad area.  If you can provide a bit of detail here or by sending an email to support@bitbucket.org that would help.

      1. Anonymous

        When I say usage, I am referring to bandwidth and request/month

        1. Okay.  See this FAQ: What kind of limits do you have on repository/file/upload size?  Other than what is discussed here, we don't have limits or restrictions.

  12. FYI - issue #3856 appears fixed, although the bug is still in the "new" status. This means the paragraph beginning:

    If the trailing slash were omitted from the URL, this link would resolve to ...

    through the workaround are no longer relevant.

    tl;dr

    I've confirmed that relative HREFs work regardless of whether the link into that directory had a trailing slash.  This is because the nginx server now replies with a 301 MOVED PERMANENTLY when redirecting with the trailing slash:

    $ curl -v http://markmevans.bitbucket.org/test-redirect
    * About to connect() to markmevans.bitbucket.org port 80 (#0)
    * Trying 207.223.240.181...
    * connected
    * Connected to markmevans.bitbucket.org (207.223.240.181) port 80 (#0)
    > GET /test-redirect HTTP/1.1
    > User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8x zlib/1.2.5
    > Host: markmevans.bitbucket.org
    > Accept: */*
    >
    < HTTP/1.1 301 MOVED PERMANENTLY
    < Server: nginx/1.2.4
    < Date: Thu, 13 Jun 2013 17:32:49 GMT
    < Content-Type: text/html; charset=utf-8
    < Content-Length: 0
    < X-Request-Count: 400
    < X-Served-By: bitbucket16
    < X-Render-Time: 0.0528440475464
    < Content-Language: en
    < Vary: Accept-Language, Cookie
    < X-Version: c61135ea5149
    < ETag: "d41d8cd98f00b204e9800998ecf8427e"
    < Location: http://markmevans.bitbucket.org/test-redirect/
    < X-Static-Version: c61135ea5149
    < Strict-Transport-Security: max-age=2592000
    < X-Content-Type-Options: nosniff
    <
    * Connection #0 to host markmevans.bitbucket.org left intact
    * Closing connection #0

     

  13. Hello, I followed the instructions but still got a 404 error. The repository is public and the index.html got content. http://bertocq.bitbucket.org/ I'm missing something or just have to wait some more minutes/hours? Thanks

    1. Berto,

      Is your repository name actually set to bertocq.bitbucket.org see an example here:

      https://bitbucket.org/tutorials/tutorials.bitbucket.org

      Mary

  14. Hi,

    Im getting this message while using my own CNAME pointing to my  repository:

    You were never here

    This user has requested we keep their identity a mystery. Let's never speak of this again.

     

    The repository is private , but i thought it didn't matter for your static website if private or public.

    Theres a index.html file in the root and just css, js files.

     

    any ideas?? or is it a DNS propogation waiting perios 24/48 hours??

    1. It sounds like you aren't going to a website but rather a repository.  What is your website?

      1. hi,

        my site is, http://git.code.droidette.co.uk/

        The CNAME setup page shows a green tick and says it resolves ok to bitbucket

        The IP is: 131.103.20.167

        1. This won't work as a site served from Bitbucket. Your website name would need bitbucket.org in the site name.  Maybe there is a misunderstanding.  What is the name of the bitbucket repository where your website resides?

          1. The website repository of the website is at: git.code.droidette.co.uk

            I've used the documentation to do this, the problem is that there's only an explanation of how to create the CNAME itself but not how to upload a site when this option is chosen.

            I used the information in the docs for creating a static website using <username>.bitbucket.org but used CNAME instead since theres no help (as stated in other threads) for how to use a  CNAME to point to a static website on bitbucket.

            I dare say using the username.bitbucket.org method is easier but the CNAME op was exactly what i wanted. The CNAME option needs removing from the docs or a clear explanation of this option needs adding to the docs. I agree with other threads who have pointed out how sketchy this option is.

            1. Bitbucket can only serve a website when the site's URL is username.bitbucket.org.  So, in your case it would need to be gitsolo.bitbucket.org.  The purpose of  CNAME is to take an existing domain and resolve it to another domain.  So, for example, if you had the domain name other.site.com you could set up your hosting service such that the hosting service forwarded visitors to gitsolo.bitbucket.org.  Each hosting service has its own means for setting up CNAMEs. I can't document that here, you need to visit your hosting service's documentation.

              You can an also point an existing domain to your Bitbucket account URL.  For that see this page: Associate an existing domain with an account.

              1. Ok, thanks for that - thats cleared up that confusion and my site is now finally working with with these changes. I took the point 'must resolve to bitbucket' literally to mean the site itself rather than a website/repository.  It might be clearer to some more than others who are more used to working with GIT, so you could add your excellent, clear explanation given in the last response to the documentation for people like me, use-to CNAME but new to GIT & GIT websites repo's.

                 

                Though i'm still not sure how this associates an existing domain name with a bitbucket account?? if people get to this website using, gitsolo.bitbucket.org then how is that associated with my own domain name with my web host?? - the way i wanted things working was to use the CNAME i created with my host to be the URL people use to get to my repo website on bitbucket?

                thank you.

                1. Anilee, I've updated the documentation. We've had a lot of fingers in this page and content has gotten munged over time.  You can setup a CNAME for your account .  You cannot set up a CNAME for a static website hosted on Bitbucket.  The account you setup a CNAME for may have a repository that represents a static website.

                  1. thanks MAnthony, got it now -

                    BTW: on the subject of Hosting Multiple Projects Under a Single Website, is there a way to create repository-subfolders on bitbucket or do we have to create the folder hierarchy on our machine then push the whole thing up to bit bucket?

                    1. Anilee,

                      You'd need to create the folder hierarchy locally and push it up to Bitbucket.

                      BTW, thank you for all your comments. They really gave me some good perspective in improving them.  (I'll be deleting the thread at some future date just to keep down on comment noise.)

                      Mary

                      1. thanks Mary,

                        this is exactly why i chose bitbucket over the others, as much as i liked the look of Source-forge/SVN and gitHub they don't seem as user friendly for DVCS noobs. Your response times and receptiveness to (constructive) issues from what ive experienced are 1st class.

                        thanks again,

                        anilee, UK

  15. Anonymous

    Is this feature supported on Stash? Is there documentation for it?

  16. I'm looking for a way to create private websites that are repository-specific and that require the same permissions to access as the repo requires. Basically I want to create a documentation website for each repository but I want full control over the page because I'm using the Apigen code generator for part of the site and it's pages are not embeddable into BitBucket like markdown pages.

    Is this possible with BitBucket?

    1. Mike, we don't support what you need.  All our websites support is on the account level, not the repository level. The best solution for you would be our Wiki's but as you point out, you can't embed an HTML page into Markdown. 

      1. Thanks for the quick reply manthony. Hopefully you can take this as a feature request, if nothing more than to be on par with GitHub?

        1. Mike, there is an outstanding request to provide this feature.  Please vote and watch it.  The team does look at votes when prioritizing features. 

          1. Thanks manthony - I upvoted. And it looks like a Top 10 feature request too.  I hope the "well into 2014 before considering" gets changed.

  17. Anonymous

    Is there a way to get Source Tree to just sync files like in Git-hub for Windows instead of having to push and pull after editing web pages.

    1. You should ask this question on answers.atlassian.com

  18. Can I use a facebook ( comments, like, share ) on a static bitbucket website?!

    1. You can try and see if it works. 

    2. It's really just static hosting, so you can do anything you like, really. The only limitation is that you cannot make authenticated requests to Bitbucket.

      1. Erik is here, Erik  is there, Erik everywhere. (smile)

        I think about authentication you're right. (wink) 


  19. Since output from rum.js is not available for the user's reference, are there any other analytics or statistics tools we can use?

  20. Hi,

    Is It possible to have some private content? 
    Is Repository information like repository list accessible through ajax? 
    Will be possible to create a custom Repository list page?

    Thanks

  21. Anonymous

    Amazing Altassian .. Awesome as always.. It would be great if some resources could be secured with bitbucket login (authentication limited to bitbucket's default login mechanism) .. I know this is already better than I expected but you know I am always greedy (wink) 

  22. R H

    Hmm, if cookies do not work, then could a jquery cookie plugin still work or not?? any way to make cookies work?

  23. R H

    Hmm, if cookies do not work, then could a jquery cookie plugin still work or not?? any way to make cookies work?

  24. Could you guys please add the necessary mime types for this hosting so that click once would work. As stated at http://robindotnet.wordpress.com/2010/06/12/mime-types-for-clickonce-deployment/ it would be ideal if you could add 

    .application –> application/x-ms-application
    .manifest –> application/x-ms-manifest
    .deploy –> application/octet-stream
    .msp –> application/octet-stream
    .msu –> application/octet-stream
    .vsto –> application/x-ms-vsto
    .xaml –> application/xaml+xml
    .xbap –> application/x-ms-xbap

    I've tried to add these by adding a .htaccess file in my repository but that does not seem to work...

    Thanks (smile)

    1. Hello and thanks for posting!

      I was going to suggest opening a feature request issue for this, but I see you already have: here. So, thanks!

      People can click on the link above and vote on this issue.

      Have an exceptional day!

      1. Thanks Dan, I did log it, but there has been absolutely no movement since then. How long does a simple request like this take?

  25. pages seem to have the http header 'X-Frame-Options' set to same origin, is this deliberate? I am trying to iframe content from one of these sites and with that header it wont work. Heres why I want to do it btw http://bb-btns.bitbucket.org/

    1. Good day Brian,

      Thanks for taking the time to comment and sorry for taking so long to reply. 

      We currently set header that way to prevent clickjacking. Of course we want to encourage your awesome site but I don't have a solution for this at the moment.

      I hope this helps, or at least answers your question.