Welcome To Beanstalk
Beanstalk is a complete workflow platform to write, review, & deploy code.
Beanstalk allows you to keep your code in a Git or Subversion (SVN) repository, perform code reviews with peers to write higher quality and bug-free code, and deploy your code from Beanstalk to your servers.
Creating Your First Repository
After signing up for Beanstalk, you’ll want to setup your first repository. Beanstalk supports both Git and SVN repositories. Not sure which one is best for you? We have a guide that goes over that topic.
When creating a repository, there are four steps. Enter a repository title, apply a color label to distinguish the repository from others, select the type of repository (Git or SVN), and enter a repository path. We recommend giving the repository title and path a memorable name. It could be the name of the project you’re working on or the name of the customer you’re working with for the project.
Setting up your Git repository in Beanstalk
To connect your computer to Beanstalk, you’ll need to have Git installed on your computer. To do that, follow our guides:
After installing Git on your computer, the next step will be to connect your repository to Beanstalk.
Generating and Adding SSH keys
To authenticate with Beanstalk for Git, you will need to generate an SSH key pair. Once your key pair is generated, you can add it to Beanstalk. Check out our Guides and Support docs to learn how to generate and an SSH key to Beanstalk:
Connecting a Git repository to Beanstalk
If you’re new to Git, please check out our guide on Getting started with Git. The guide goes over the basics of creating a new local repository and connecting that repository to a remote repository.
Connecting an existing repository to Beanstalk
Locally, if you have a repository that’s a Git repository, it’s possible to add that to Beanstalk. To do so, open your command line application and type the following command:
cd project-directory
git remote add beanstalk https://accountname.git.beanstalkapp.com/project_name.git
git push beanstalk --allThe command will send your repository to Beanstalk and include all repository Git history.
Choosing a Git client
Clients exist for Mac, Windows, and Linux that help you get the most out of Git. We maintain a list of recommended clients in our Support docs.
Creating your first Git commit
In Git, commits are changes saved to the repository. Every commit includes a commit message. A commit message is a short message describing the changes you made in the repository. A great commit message will explain the reasoning behind a change and any possible drawbacks from the modification. To learn more about great commit messages, check out our blog post on meaningful commit messages.
A Git commit is done through a Git Client or the command line. To make a commit, run the following command in the command line while in your file directory.
git commit -m "My first commit!"The “-m” switch signifies that the following is the commit message. Multiple messages are possible; they will appear as separate paragraphs.
In Git, a commit saves the changes to your local repository. To send the changes to the remote repository on Beanstalk, you'll need to use the git push command. Here's how it looks:
git push Beanstalk stagingSetting up your SVN repository in Beanstalk
In Beanstalk, when creating an SVN repository you have three options: Create the repository from scratch, import from URL, and upload a file.
- Create the repository from scratch: This will create a new empty repository.
- Import from URL: This is great if you are migrating from another SVN server or looking to import SVN files.
- Upload a file: Uploading a file is like Import from URL, the difference being if the file is on your local machine.
We recommend using SVN with a client. In our support docs, we maintain a list of SVN Clients in our Support docs.
To learn more, please check out our Creating your Subversion repository help doc.
Creating your first Commit in SVN
In SVN, a commit is a way to send the changes from your local working copy to the remote repository. Like Git, you can include a message with your commit.
An SVN commit is done from your SVN Client or the command line. To make a commit from the command line, navigate to your directory that’s under version control and run the following command.
$ svn commit -m "My first commit!"
The “-m” switch signifies that the following is the commit message. In SVN, the commit will send the changes to your remote repository.
Beanstalk Tools
To make collaboration as seamless as possible, Beanstalk has built-in tools to get the most out of Subversion and Git.
- Blame: See who last touched every line of code. When you want to know who is responsible for a particular line of code, blame gives you the user, revision, and comment on the last change made to that line.
- Preview: Instantly preview HTML and image files within Beanstalk, compare versions side by side, and share them with your team, colleagues, and people outside of your Beanstalk account.
- Diff: Easily compare any two revisions of a file to see what changed.
Repository Settings
Each repository has its own Settings page. Repository specific settings make sure a repository works as you and your team expect. These settings are only available to Account Owners and Admins.
General
General details: See how much storage your repository is using. Change your repository title and assign a color for the repository so it’s identifiable.
Repository URL: This allows you to change your repository URL. Please be aware that this can have adverse effects and your local Git and SVN configuration for remote repositories will have to be updated. To learn more about changing your repository view our support documentation on the topic.
Default branch (Git only): This is where you can change the default branch in the Beanstalk browser. This will be the default branch when you clone the repository, browse the source in Beanstalk, or attempt a merge.
Advanced settings (Git only): By default, Fast-Forward pushes are disabled in Beanstalk. In this section, you can enable Fast-Forward pushes. Before enabling, please review our support documentation.
Require Commit Messages (SVN only): Reject any commit without a commit message.
Configure Subversion Directories (SVN only): Add custom names for your trunk, branch, and tags paths.
Export / Dump repository (SVN only): For SVN repositories this allows you to create an export or dump file.
Repository-wide deployment key: Adding this public key to the physical servers you’re deploying to, all deployments in this repository will be able to deploy through SSH/SFTP.
Delete repository: A deletion is permanent; please make sure you have all necessary backups before deleting a repository.
Permissions
This page allows you to see what specific teams and users have permissions to a repository. Along with what permissions, they have in the repository. You can also take the repository permissions a step further by limiting access to particular branches. By doing this you could allow users to push to a staging branch (or similar), but limit push access to a master branch.
With SVN repositories there is the ability to enable Anonymous access. This opens your repository to anyone with a repository link to have read-only permissions.
Integration
Beanstalk integrates with many other web services to extend the capabilities of Beanstalk. For instance, through a commit message you close a JIRA ticket or upon successful deployment you can notify a Slack channel. There are three primary types of services Beanstalk integrates with.
Issue Tracking/Project Management:
Time Tracking:
Team Discussion:
Continuous Integration (CI)
Using Modular or Classic Webhooks or the Beanstalk API you can build you own integration.
Beanstalk also integrates with Zapier allowing you to create integrations with hundreds of other services.
Code review
Approval policy: Define how a code review is considered approved for all reviews in a repository.
Automatically reopen approved reviews: When new commits are made, automatically reopen code reviews for branches.
Default assignees: Set a user to be assigned to all code reviews. Please keep in mind, when a code review is requested, the assignee cannot be adjusted.
Default watchers: Similar to Default assignee, a user set as a watcher on all new code reviews in the repository. Please keep in mind, when a code review is requested, the assignee cannot be adjusted.
Please note: At the bottom of the page there is the ability to save the changes you’ve made.
Mark all commits as Approved: If there are many commits in a repository that need to be approved, they can be bulk approved. Depending on the number of commits to be approved this process might take a few minutes.
Sharing
Keep track of currently shared previews, if the preview is public, the URL of the preview, who shared the preview, and delete the shared preview.
Any user can share a Preview. However, the public sharing option is only available to Admins and the Account Owner. Sharing a preview does not affect the security of your repository, someone viewing a preview is can only see the contents of the preview and click on links in the HTML.
Managing User Accounts In Beanstalk
An important part of managing your Beanstalk account is managing user accounts. Correctly configuring these settings ensures users have the best experience possible when using Beanstalk. Below you’ll learn how to add user accounts and what permissions and roles those users can be a part of.
Add User Accounts
Users can be added and managed by clicking on “Users” in the top header in Beanstalk. There are four different roles a user account can have in Beanstalk.
Account Owner: An account owner is the only user that can delete repositories, access and change billing information, and the Beanstalk Account section. By default, the owner is the user that created the Beanstalk account. There is only one Beanstalk account owner, though the account owner can assign a user to take over the role.
Admin: Admins can manage user accounts, repository permissions, and deployment permissions.
Regular User: User accounts that have access to standard features like gaining access to a repository or deploying to an environment.
Anonymous User (SVN Only): Allow anyone to access a repository to see the files in a repository. Anonymous users can read files in a repository and cannot commit changes.
It is good practice to keep Admins and your Account Owner up to date.
Teams: It’s common to have users with similar functions, like QA. To simplify repository permissions, you can group these users together into Teams.
Repository Permissions
Repositories can also have permissions for user accounts. This allows a user to only the access the repositories and deployments they need to. A user account can have the following permissions on a repository.
No Access: They are not allowed to see or access a repository.
Read-Only: The user account can view, and pull/checkout a repository. For Git repositories the user is unable to Push to a repository. For SVN repositories the user is unable to commit changes to the remote.
Read-Write: The user account can view, pull/checkout, and push/commit to a repository.
A user account can have the following permissions on a deployment:
View Activity: Allows a user to see all deployment activity, view revision history on a deployment. If an environment has automatic deployments enabled they will be able to deploy to the environment.
View & Deploy: The permissions of View Activity along with the ability to trigger manual deployments and retry failed deployments.
Environment Access: The permissions of View & Deploy, but on specific environments. For example, you could give a group of users View and & Deploy permissions to the Staging environment while not giving them permission to the Production environment.
Full Access: The permissions of View & Deploy and the ability to add/edit server environments. They also able to view deployment incidents.
Team Permissions
Teams carry the same permissions of User Accounts, but allow you to group common users together to simplify permissions. For example, you could have a QA Team where every QA member is given access to QA Environments without having to add each user to have access to the environment.
Please note: User accounts inherit the permissions from teams they are a part of.
Managing Your Beanstalk Account
Beanstalk account settings are configurable to your exact needs. Whether you need to change your Account Owner or get a receipt for your last payment, it’s found in the account settings. Take a few minutes getting yourself familiar with the different sections available here.
Please note: Managing your Beanstalk Account is only available to Account Owners.
Account Settings
In this section, you can edit information about your Beanstalk account. You can modify account details like company name, change the Account Owner, and change the Beanstalk account URL.
There is the ability to enable the Developer API to build tools and services around Beanstalk. In some cases, a Git or SVN client will require the API to be enabled.
If you wish, your Beanstalk account can also be canceled from the Account Settings section.
Plans & Billing
The Plans & Billing section is where you can edit your credit card information, update your plan details, change who receives your Beanstalk receipts and view past receipts.
Beanstalk security features
Two-Step Verification: This requires users to enter a token along with their username/password when logging in. A user can receive the token to their phone via SMS, or use Google Authenticator.
Enforce Strong Passwords: Users will be required to create strong passwords associated to their Beanstalk account. Users with weak passwords will be prompted to update their password.
RSS Feed Authentication: When accessing a repository RSS feed (view commits) users will be prompted to enter username/password. To learn more about RSS feeds check out our support doc on the topic.
Disabling Automatic Login: Prevent users from using Beanstalk’s “Remember Me” when logging in. Users will have to enter username/password manually for each login.
Restrict Access by IP Address: Restrict repository access to only a specific set of IP addresses or a range of IP addresses. These settings will affect all repositories in your account.
Please note: Restricted IP addresses on Beanstalk does not apply to the Account Owner.
View IP Access History: In a CSV format we allow you to download connection history to your account. By looking at this file, you can easily review the following information for each of the last 10 connections per user.
Amazon S3 Backups
While Beanstalk regularly backs-up all data, it also includes the ability to backup repository data to Amazon S3 Buckets. These backups are run nightly and are only available to business plans.
To connect your Beanstalk account to Amazon S3 you’ll be prompted to enter your AWS S3 Region, Access Key, Secret Key, and Bucket.
Should a backup to an S3 Bucket fail for any reason, Beanstalk will generate an incident and contact the Account Owner via email.
User Account Settings
Individual accounts in Beanstalk have specific settings. Have your team take a look at these settings, so they receive the notifications they want, have the correct time zone set, and much more.
Profile
From updating a password to managing a two-step verification number each user added to Beanstalk can edit profile information.
Personal Information: Change your full name as it displays in Beanstalk, update your email address, and change your Beanstalk username.
Change Password: You can update your password here. We always recommend using a strong password for your Beanstalk account.
Two-step Verification: If your account is set to use Two-step verification you’ll be able to set and update your phone number the token is sent to (via SMS), and configure Google Authenticator. Think about setting a backup number, if your primary phone number becomes unavailable you’ll be unable to access your account.
Profile Photo: For profile photos, Beanstalk uses Gravatar for profile photos. Sign-up for a free Gravatar account with your email address to create a profile photo.
Time zone: To ensure that the proper time zone displays across Beanstalk for your account.
Please note: At the bottom of the page there is the ability to save the changes you’ve made.
Close open sessions: If you’re concerned about browser sessions open at other locations you can force those sessions to be signed out here.
Email Notifications
Beanstalk can send you notifications of your commits. On a repository level there are four different notifications you can sign-up to receive:
- Commit Notifications: Receive an email when there is a commit to the repository.
- Deployments: Receive an email when there is a deployment to an environment in the repository.
- Daily Digest: A daily summation of commits, deployments, and comments made on a repository.
- Incidents (Account Owner & Admin only): There can be incidents with various features of Beanstalk. For example, a failed deployment. If an incident is triggered, you’ll receive an email.
You can also opt-in to receive the Beanstalk newsletter.
SSH Keys
Add a SSH public key from your machine to authenticate your account. To learn more about SSH Keys, visit our support docs on how to add them from Windows and Mac. And be sure to read our guide on tips for using SSH Keys.
Access Tokens
Connecting to the Beanstalk API is done through access tokens associated with your user account. Creating a token is as simple as clicking on “Generate a token”. To ensure account safety, we recommend storing your access token in a safe place and rotating the token on a regular basis. To learn more about our API check out our API documentation.
The Beanstalk Dashboard
The dashboard provides a starting point for accessing repositories and gives a high-level overview of what your team is working on. To achieve this it shows the following:
Repositories: The last 14 days of commit activity is visible including contributors, ordered by most recent commits.
Your Assigned Code Reviews: Active code reviews you’re assigned to along with the names and branches of your code reviews.
Manual Deployments: We recommend production environments set to as manual deployments. With this thinking, this section shows your most recent manual deployments.
Top Committers: This lets you see what your team is working on and who has pushed the most commits to Beanstalk, broken down by the repository.
Code Reviews
Beanstalk includes the ability to do code reviews. Code reviews are a fantastic way to share skills across team members. It ensures your team follows best practices and ships the best code possible. To learn more about code reviews we have an excellent guide on the topic.
Deployments
The final piece of the puzzle for a great development workflow is a robust deployment workflow. Beanstalk allows you to deploy to multiple environments, servers and automate the process. To learn about deployment best practices and our recommended workflow check out our deployment guide.
We’re here to help
If you have any questions, our Success team is a Live Chat, Tweet, Email, or support doc away. Never hesitate to contact us, we want to make your experience using Beanstalk the best experience possible.